# @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;
- one shared research prompt for every surface.

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

```ts
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 query = structureSearch?.schema.parse({ operation: "files", path: "/ABS/repo" });
```

`@octocodeai/octocode-core/mcp` exports `buildMcpInstructions`, `buildCliInstructions`, `buildGrammarCapabilityInstruction`, `publishedInputSchema`, and the deferred-tool dispatcher definition. Both instruction builders return the same constant prompt: one `<section>` per line (`<local>`, `<github>`, `<packages>`, `<clasify>`, `<pages>`, `<evidence>`, `<cli>`), within 2,000 characters and 1,600 bytes. Where a tool can be missing, the prompt says so in plain words. `buildMcpInstructions` still accepts the enabled tool names for existing callers and ignores them. Each tool has one description, the same on every surface; the lspSearch description adds the language servers the runtime found.
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` answers bounded typed questions when an explicit classification or a
semantic judgment can change the next action. Send `{queries:[...]}`; each query
is one matrix of `resources[]` × `questions[]`. Every question is applied to
every resource, and each resource is captured once. Use one matrix when the same
questions apply to every resource; use separate matrices when the resource sets
differ. Skip exact or settled checks: exact search, AST/LSP, or a bounded read
settles them.

A resource is `{id, value}` for non-empty supplied state, or `{id, tool, query}`
for one unexecuted read-only Octocode call (`prefilter` rare literals pick
windows in large files). A question is `{id, type, ask}`. `type` is one of
`locate` (scored line windows), `sufficient`, `relevant`, `supports`, `adds`
(with `known` facts), `yesno`, `choice`, or `score` (with `labels`). `ask` holds
one atomic fact. Omitted IDs are derived by position; supplied IDs stay stable
in the results. The matrix `mainGoal` and `reasoning` are sent to the judge.

```json
{
  "queries": [
    {
      "resources": [
        {
          "id": "local-store",
          "tool": "localFetch",
          "query": { "path": "/ABS/repo/src/store.ts", "ranges": ["80-150"] }
        }
      ],
      "questions": [
        {
          "id": "durability",
          "type": "relevant",
          "ask": "Acknowledged writes survive a process crash."
        }
      ]
    }
  ]
}
```

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 read tool before you write its query.
Read 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 25 questions. A batched call accepts at most five matrices and 50 total
cells. A resource's `maxChars` defaults to 80,000 and caps captured file
content; select the smallest complete section with the read query. An oversized
first page returns `classificationContextTooLarge` without a provider call. The
runtime follows supported read continuations within the cap. Replay
`next.clasify` unchanged when returned.

Results keep the query, resource, question, and page IDs. Retrieved bodies are
not returned. Read the best verification window first (and both near-ties);
expand the read when deciding evidence is missing. Partial, uncertain,
insufficient, and errored pages stay in the result; bounded coverage is not
exhaustive and cannot prove global absence. Read deciding source and run the
applicable exact checks before you make claims or changes.

## 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` 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.

```ts
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 (it sets `page`) unchanged.
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.