# @octocodeai/octocode-core

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

- public tool names, descriptions, executable input and output schemas, and relations;
- shared research instructions selected for the exposed tools;
- reusable TypeScript result types.

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 { AstSearchQuerySchema } from "@octocodeai/octocode-core/schema";
import { buildMcpInstructions } from "@octocodeai/octocode-core/mcp";
import type {
  GitHubSearchCodeData,
  LocalSearchCodeData,
} from "@octocodeai/octocode-core/types";
import type {
  GitHubDirectoryFileEntry,
  LocalFetchToolResult,
} from "@octocodeai/octocode-core/extra-types";

const instructions = buildMcpInstructions(["ghSearch", "ghGetFileContent"]);
const query = AstSearchQuerySchema.parse({
  operation: "files",
  path: "/ABS/repo",
});
```

`@octocodeai/octocode-core/mcp` also exports `SYSTEM_PROMPT` for the full catalog.
CLI context and MCP servers consume these same contracts. The package contains no tool runners, CLI command registry, or skill bundle.
Its output schemas define transport-neutral result envelopes and tool-specific
data fields; execution packages remain responsible for producing and enforcing
them. This includes the six-route `jevReasoning` contract: core bounds and
describes the typed decision input, including optional shareable supplemental
context and an optional public observations/uncertainty summary. Native places these in provider state; neither requires private reasoning. Native owns credential-gated
availability, deterministic preflight gates, provider access, and provisional
output policy.

`jevScout` batches independent Score questions over bounded excerpts. Open
`requiredReads` (both `read` and `gray_read`), inspect `truncated` and coverage,
and reopen anchors before citing behavior. A budget-truncated rejection remains
`gray_read`; a skip never proves absence. Its default taxonomy is `implements`;
use an explicit `relevance` dimension for fetched history rows. `level` is the
most probable rubric level, while `score` is the provider expectation.

## 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:

```bash
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
```

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.

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