@octocodeai/octocode-core

@octocodeai/octocode-core

Shared, versioned contracts that are independent of Octocode tool execution:

• public agent-facing tool definitions with names, descriptions, executable input schemas, and schema-owned branch diagnostics;
• shared research guidance rendered for each surface’s available capabilities.

Import public tool contracts from @octocodeai/octocode-core/schema. Execution, security, provider access, availability, and response shaping belong to the Rust @octocodeai/octocode-native runtime; core imports no execution or native engine.

Imports

import {
  DIRECT_TOOL_DEFINITIONS,
  TOOL_NAMES,
} from "@octocodeai/octocode-core/schema";
import { buildMcpInstructions } from "@octocodeai/octocode-core/mcp";

const instructions = buildMcpInstructions();
const structureSearch = DIRECT_TOOL_DEFINITIONS.find(
  (tool) => tool.name === TOOL_NAMES.STRUCTURE_SEARCH,
);
const request = structureSearch?.inputSchema.parse({
  queries: [{ operation: "files", path: "src" }],
});

@octocodeai/octocode-core/mcp exports the shared MCP and CLI instructions, published input schemas, and the deferred-tool dispatcher definition. Tool descriptions guide selection; input schemas own fields and limits. Inspect the available tools and their live schemas before constructing a call. Pass the native catalog’s availableTools and selection to the instruction builders; with neither classification route available, they omit classification guidance.

CLI context and MCP servers consume DIRECT_TOOL_DEFINITIONS, the public projection exported from @octocodeai/octocode-core/schema. These definitions intentionally omit output schemas. CLI and MCP discovery therefore advertise only the agent-facing input contract.

Optional clasifyContext selects evidence before it reaches the host on localFetch, localSearch, ghGetFileContent, and ghSearchCode when a classification API credential is configured. Its classifiers array contains one to five atomic evidence questions. _selection.ts owns the shared fields; each tool declares its assessment scope. Native uses clasifyTemplates.ts and the same JEV evaluator as standalone clasify.

Search assesses captured hit snippets per file, not hidden whole-file bodies. Fetch assesses complete raw line windows. Selected evidence returns in source order with selected/excluded/unknown counts and explicit unfiltered recovery. Prefer selection for noisy local search, large local fetches and scoped GitHub fetches. Keep exact reads, GitHub search and AST/LSP identity checks ordinary. Questions cannot recover a lexical miss. Optional mainGoal and reasoning add context without activating selection. Omit clasifyContext for ordinary retrieval. Public clasify additionally follows its beta and tool-list gates. The retired top-level goals, classifiers, and ranking controls have no aliases.

TOOL_NAMES, DIRECT_TOOL_DEFINITIONS, and getToolSchemaVariants are the single public sources for identities, contracts, and variants. Each input schema owns its branch relations and diagnostics. Core input schemas preserve accepted caller values; they may add documented defaults or reject invalid input, but never clamp or silently discard it.

The canonical internal specifications retain output schemas for native contract generation, result validation, and contract fingerprinting. They are not part of the public /schema export. Execution packages remain responsible for producing and validating result envelopes. This package contains no tool runners, CLI command registry, or skill bundle.

clasify exposes JEV's noul, choice, score and experimental box questions, preserving keyed answers, probabilities, legends, model and usage. Each evaluation row in {queries:[...]} supplies keyed questions and exactly one of held state or an unread text source: a localFetch or ghGetFileContent reference with ranges or fullContent:true, or an HTTPS url. Native captures the complete selection internally and returns a read suggestion in the hints string array, pinned to the same snapshot or commit, never the body. A suggestion names the tool and its JSON input. An object in state remains data. mainGoal and reasoning remain metadata.

The section-research contract adds {operation:"sections",resources,questions} for one to 25 named local/GitHub/HTTPS text resources and one shared set of one to 25 typed questions. Whole-source and image evaluation remain available. Section results group keyed outcomes under each resource, retaining source version, a structured executable resources.<key>.read reference, exact target/context coordinates and cumulative coverage. Every settled section carries every question outcome: answered, error, unsupported or unassessed. A Choice label such as "unknown" remains an answered value; no universal threshold changes its type. Section answers omit the repeated type and Score legend: both come from the shared questions. Each answer retains its value, confidence and full distribution.

next.nextSectionPage resumes assessment with an opaque assessment token; responsePagination.next reads immutable settled output without inference. The frozen work plan binds the resources, questions, model and access context. Each settled section is emitted once across assessment batches; display fragments use rowPart, with shared questions on the first fragment. Coverage is cumulative and must not be added across batches. A terminal row can retain its resources and coverage alongside a canonical error.

Development status: the section contract is implemented; runtime integration and end-to-end validation are pending. These are contract requirements, not measured quality or token savings.

For unread images, assets maps opaque placeholders used in state or question strings to {type:"image",source:...}. Image origins reuse local/GitHub reader identity fields or an HTTPS URL; they take no text selectors. Native supplies PNG/JPEG bytes and the provider's experimental image header. Results expose image dimensions, digest, pinned origin and an expiring inspection path, never base64. Box answers retain normalized coordinates and nullable confidence. Octocode permits up to eight images, 8 MiB each and 16 MiB total, bounded to 256–1,568 pixels per edge and 78,400–2,458,624 pixels per image.

A separate {operation:"models"} row lists the account's provider models. longContext:true opts into the provider's experimental long-context header and raises Octocode's complete-state bound from 32,000 to 256,000 characters; the provider may still reject a request. These are Octocode resource bounds, not provider context guarantees. Inspect octocode schema clasify --view query for the full contract, including optional/null provider question fields.

Answers are bounded judgments, not proof: read the deciding lines before a source claim. A failed or oversized row returns an error, never a negative answer. Exact reads and AST/LSP identity checks remain the better starting point when the target or binding is already known.

Consumers

This package only authors contracts. The octocode monorepo's @octocodeai/config is the single generator: after changing a schema here, build this package and run yarn contracts:regen in the octocode repo. That writes packages/octocode-config/contract/ (the native enforcement contract, fixtures, provenance, and generated Rust types) plus the TypeScript tool types exported from @octocodeai/config/schema; octocode-native embeds contract/ at build time. Name a vocabulary shared across tools with .meta({ title: "Name" }) so it becomes one generated type everywhere.

The build also writes dist/public-catalog.json and one exact agent-facing contract per tool under dist/schema-templates/. Use those generated files for schema review and size measurement; they include the full public input/query contract and intentionally exclude output schemas, matching MCP and CLI discovery.

Package discovery and lookup

artifactSearch finds packages by name or discovery terms and returns registry metadata, including upstream source links when available. For example:

{ "queries": [{ "ecosystem": "npm", "packageName": "@types/node" }] }

Use octocode schema artifactSearch --view query for supported ecosystems, version rules, pagination, and registry options. PyPI supports exact lookup, not keyword discovery; registryUrl applies only to npm. Registry metadata is a lead to source code, not proof of implementation behavior, and artifactSearch does not install packages.