@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 instructions selected for the exposed tools.

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([
  TOOL_NAMES.GITHUB_SEARCH,
  TOOL_NAMES.GITHUB_FETCH_CONTENT,
]);
const astSearch = DIRECT_TOOL_DEFINITIONS.find(
  tool => tool.name === TOOL_NAMES.AST_SEARCH,
);
const query = astSearch?.schema.parse({ operation: "files", path: "/ABS/repo" });

@octocodeai/octocode-core/mcp also exports SYSTEM_PROMPT for the full catalog. 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.

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 applies bounded typed questions when a semantic judgment can change the next action. Use one matrix when the same question set applies to every resource; each resource is captured once and every questions[] entry is applied to every resources[] entry. Use {queries:[...]} only to batch independent complete matrices. Do not use it for exact or settled checks, or to reread evidence already in context.

A resource context is either {value: ...} for non-empty supplied state or {tool, query} for one unexecuted read-only Octocode call. Questions are typed as Noul, Choice, or Score. Every matrix requires non-blank reasoning that states why the judgment changes the next action. Every query, resource, and question has a stable ID, and results correlate those IDs with each assessed page:

{
  "id": "store-candidates",
  "reasoning": "Classify every captured page before selecting proof reads.",
  "resources": [
    {
      "id": "local-store",
      "maxChars": 16000,
      "context": {
        "tool": "localFetch",
        "query": {
          "path": "/ABS/repo/src/store.ts",
          "chunkType": "bytes",
          "offset": 0,
          "chunkSize": 16000,
          "reasoning": "Capture one bounded source page."
        }
      }
    },
    {
      "id": "browser-body-2",
      "context": { "value": { "artifact": "bounded saved browser chunk" } }
    }
  ],
  "questions": [
    {
      "id": "relevance",
      "question": {
        "type": "choice",
        "instructions": "Does this resource contribute to the decision?",
        "criteria": {
          "relevant": "Contains evidence that can change the next action.",
          "insufficient": "The bounded view is incomplete or undecidable.",
          "unrelated": "Contains no relevant evidence."
        }
      }
    },
    {
      "id": "risk",
      "question": {
        "type": "score",
        "instructions": "How much direct verification does this resource need?",
        "criteria": ["None", "Targeted read", "Must inspect"]
      }
    }
  ]
}

Run octocode clasify '<json>' or octocode clasify --input request.json. Inspect the live query contract with octocode scheme clasify --view query --compact, and inspect the selected context tool before constructing an ordinary query. Context tools are read-only; recursive assessment, rewrites, and cloning are excluded.

Each matrix is capped at 25 resource-question cells, with at most 25 resources and five questions. A batched call accepts at most five complete matrices and 50 total cells. A resource's maxChars defaults to 80,000; lower it when a smaller assessment bound is sufficient. The runtime follows safe ordinary-tool continuations within that bound and returns next.clasify when more source scope remains.

Results contain typed answers, requested and resolved model identities, usage, coverage, and a body-free context receipt. Retrieved bodies are not returned. Retain partial, uncertain, insufficient, and errored pages; bounded coverage is not exhaustive and cannot prove global absence. Read deciding source and run the appropriate exact checks before making claims or changes. A new assessment reruns inference, so reuse current evidence and prefer direct checks for exact facts.

Native contract generation

Build this package before generating native contracts because the generator loads dist/. The generator rejects package changes that are not committed, so a checked artifact always names a clean source revision:

yarn workspace @octocodeai/octocode-core build
node packages/octocode-core/scripts/generate-native-contracts.ts \
  --out /ABS/octocode/packages/octocode-native/crates/runtime/src/contracts/generated

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.

Use --allow-dirty only for local iteration. Generated output includes contract-provenance.json, which records the core commit, dirty state, and contract fingerprint. Release and verification flows must run without --allow-dirty.

Package discovery and lookup

artifactSearch replaces npmSearch. Use it to find a package for a capability, resolve a known dependency to registry metadata, or locate upstream source. Choose one required type per query: npm, pypi, crates, maven, nuget, go, packagist, or rubygems. Python/pip/uv uses pypi; Rust/Cargo uses crates. Registry metadata does not establish implementation behavior.

import { ArtifactSearchBulkQueryLocalSchema } from "@octocodeai/octocode-core/schema";

const packages = ArtifactSearchBulkQueryLocalSchema.parse({
  queries: [
    { type: "npm", packageName: "@types/node" },
    { type: "pypi", packageName: "requests" },
    { type: "crates", keywords: ["schema", "validation"] },
    { type: "maven", packageName: "org.slf4j:slf4j-api" },
  ],
});

Set exactly one of packageName or keywords (an array even for one term). PyPI supports exact lookup only; keyword queries report unsupported keyword discovery. Keyword pages default to 10 artifacts, with pageSize up to 100. Continue by copying the complete returned next.nextPage query and opaque cursor unchanged. Do not use numbered page fields. Bulk requests contain one to five queries; whole-response pagination retains the shared response snapshot envelope.

Only type: 'npm' accepts registry; existing npm scope mappings and configured credentials remain authoritative. Other ecosystems use official public services. Results expose normalized artifacts[] metadata with source links when supplied by the registry. Use local tools to inspect installed code, or source tools directly when its repository is already known. This tool does not install packages.