@octocodeai/octocode-tools-core 16.6.3 → 17.0.2

package/dist/tools/lsp/semantic_content/scheme.d.ts

@@ -79,6 +79,19 @@ export declare const BulkLspGetSemanticsQuerySchema: z.ZodObject<{
 export declare const LspGetSemanticsOutputSchema: z.ZodObject<{
     base: z.ZodOptional<z.ZodString>;
     shared: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    responsePagination: z.ZodOptional<z.ZodObject<{
+        charOffset: z.ZodNumber;
+        charLength: z.ZodNumber;
+        totalChars: z.ZodNumber;
+        hasMore: z.ZodBoolean;
+        nextCharOffset: z.ZodOptional<z.ZodNumber>;
+        currentPage: z.ZodOptional<z.ZodNumber>;
+        totalPages: z.ZodOptional<z.ZodNumber>;
+        chunkMode: z.ZodOptional<z.ZodEnum<{
+            semantic: "semantic";
+            "char-limit": "char-limit";
+        }>>;
+    }, z.core.$strip>>;
     results: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         id: z.ZodString;
         status: z.ZodLiteral<"empty">;
@@ -360,9 +373,33 @@ export declare const LspGetSemanticsOutputSchema: z.ZodObject<{
                 nextPage: z.ZodOptional<z.ZodNumber>;
                 pageSize: z.ZodOptional<z.ZodNumber>;
                 totalItems: z.ZodOptional<z.ZodNumber>;
+                perPage: z.ZodOptional<z.ZodNumber>;
+                totalFound: z.ZodOptional<z.ZodNumber>;
+                returned: z.ZodOptional<z.ZodNumber>;
+                totalMatches: z.ZodOptional<z.ZodNumber>;
+                reportedTotalMatches: z.ZodOptional<z.ZodNumber>;
+                reachableTotalMatches: z.ZodOptional<z.ZodNumber>;
+                totalMatchesKind: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    reported: "reported";
+                    lowerBound: "lowerBound";
+                }>>;
+                totalMatchesCapped: z.ZodOptional<z.ZodBoolean>;
+                totalResults: z.ZodOptional<z.ZodNumber>;
+                itemsPerPage: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             summary: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            next: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                tool: z.ZodString;
+                query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                why: z.ZodOptional<z.ZodString>;
+                confidence: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    heuristic: "heuristic";
+                }>>;
+            }, z.core.$strip>>>;
+            hints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
@@ -651,9 +688,33 @@ export declare const LspGetSemanticsOutputSchema: z.ZodObject<{
                 nextPage: z.ZodOptional<z.ZodNumber>;
                 pageSize: z.ZodOptional<z.ZodNumber>;
                 totalItems: z.ZodOptional<z.ZodNumber>;
+                perPage: z.ZodOptional<z.ZodNumber>;
+                totalFound: z.ZodOptional<z.ZodNumber>;
+                returned: z.ZodOptional<z.ZodNumber>;
+                totalMatches: z.ZodOptional<z.ZodNumber>;
+                reportedTotalMatches: z.ZodOptional<z.ZodNumber>;
+                reachableTotalMatches: z.ZodOptional<z.ZodNumber>;
+                totalMatchesKind: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    reported: "reported";
+                    lowerBound: "lowerBound";
+                }>>;
+                totalMatchesCapped: z.ZodOptional<z.ZodBoolean>;
+                totalResults: z.ZodOptional<z.ZodNumber>;
+                itemsPerPage: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             summary: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            next: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                tool: z.ZodString;
+                query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                why: z.ZodOptional<z.ZodString>;
+                confidence: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    heuristic: "heuristic";
+                }>>;
+            }, z.core.$strip>>>;
+            hints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>;
     }, z.core.$strip>]>>;
 }, z.core.$strip>;

package/dist/tools/lsp/semantic_content/semanticAnchored.d.ts

@@ -0,0 +1,7 @@
+import { acquirePooledClient } from '@octocodeai/octocode-engine/lsp/manager';
+import type { SymbolAnchor } from '../shared/resolveSymbolAnchor.js';
+import type { LspSemanticEnvelope, SymbolAnchoredSemanticQuery } from '../shared/semanticTypes.js';
+declare const CONSUMER_SCOPED_TYPES: ReadonlySet<string>;
+export { CONSUMER_SCOPED_TYPES };
+export declare function warmLikelyConsumers(client: NonNullable<Awaited<ReturnType<typeof acquirePooledClient>>>, anchor: SymbolAnchor, workspaceRoot: string): Promise<void>;
+export declare function dispatchAnchoredSemantic(query: SymbolAnchoredSemanticQuery, anchor: SymbolAnchor, client: NonNullable<Awaited<ReturnType<typeof acquirePooledClient>>>): Promise<LspSemanticEnvelope>;

package/dist/tools/lsp/semantic_content/semanticEnvelopes/callEnvelopes.d.ts

@@ -0,0 +1,5 @@
+import { acquirePooledClient } from '@octocodeai/octocode-engine/lsp/manager';
+import { type LspSemanticEnvelope, type SymbolAnchoredSemanticQuery } from '../../shared/semanticTypes.js';
+import type { SymbolAnchor } from '../../shared/resolveSymbolAnchor.js';
+export declare function callsEnvelope(query: SymbolAnchoredSemanticQuery, anchor: SymbolAnchor, client: NonNullable<Awaited<ReturnType<typeof acquirePooledClient>>>): Promise<LspSemanticEnvelope>;
+export declare function typeHierarchyEnvelope(query: SymbolAnchoredSemanticQuery, anchor: SymbolAnchor, client: NonNullable<Awaited<ReturnType<typeof acquirePooledClient>>>): Promise<LspSemanticEnvelope>;

package/dist/tools/lsp/semantic_content/semanticEnvelopes/envelopeHelpers.d.ts

@@ -0,0 +1,20 @@
+import { type LspGetSemanticsQuery, type LspSemanticEnvelope, type SemanticEmptyCategory, type SemanticContentType } from '../../shared/semanticTypes.js';
+import type { SymbolAnchor } from '../../shared/resolveSymbolAnchor.js';
+export declare const DEFAULT_SYMBOLS_PER_PAGE = 40;
+export declare const DEFAULT_LOCATIONS_PER_PAGE = 40;
+export declare const DEFAULT_CALLS_PER_PAGE = 10;
+export type PaginationInfo = {
+    currentPage: number;
+    totalPages: number;
+    totalResults: number;
+    hasMore: boolean;
+    itemsPerPage: number;
+    nextPage?: number;
+};
+export declare function emptyCategoryForReason(type: SemanticContentType, reason: string): SemanticEmptyCategory;
+export declare function failedAnchorEnvelope(query: LspGetSemanticsQuery, reason: string): LspSemanticEnvelope;
+export declare function emptyEnvelope(type: SemanticContentType, anchor: SymbolAnchor, reason: string, serverAvailable?: boolean): LspSemanticEnvelope;
+export declare function paginateItems<T>(items: readonly T[], requestedPage: number, requestedItemsPerPage: number): {
+    pageItems: T[];
+    pagination: PaginationInfo;
+};

package/dist/tools/lsp/semantic_content/semanticEnvelopes/locationEnvelopes.d.ts

@@ -0,0 +1,13 @@
+import type { LSPRange, ReferenceLocation, ReferencesByFile, CodeSnippet } from '@octocodeai/octocode-engine/lsp/types';
+import { type LspSemanticEnvelope, type SymbolAnchoredSemanticQuery } from '../../shared/semanticTypes.js';
+import type { SymbolAnchor } from '../../shared/resolveSymbolAnchor.js';
+export declare function locationsEnvelope(query: SymbolAnchoredSemanticQuery, anchor: SymbolAnchor, kind: 'definition' | 'typeDefinition' | 'implementation', provider: string, locations: CodeSnippet[]): LspSemanticEnvelope;
+export declare function referencesEnvelope(query: SymbolAnchoredSemanticQuery, anchor: SymbolAnchor, locations: CodeSnippet[]): LspSemanticEnvelope;
+export declare function hoverEnvelope(_query: SymbolAnchoredSemanticQuery, anchor: SymbolAnchor, hover: unknown): Promise<LspSemanticEnvelope>;
+export declare function buildReferencesByFile(locations: readonly ReferenceLocation[]): ReferencesByFile[];
+export declare function normalizeHover(hover: unknown): {
+    markdown?: string;
+    text?: string;
+    range?: LSPRange;
+};
+export declare function stringifyHoverPart(part: unknown): string;

package/dist/tools/lsp/semantic_content/semanticEnvelopes.d.ts

@@ -0,0 +1,3 @@
+export { DEFAULT_SYMBOLS_PER_PAGE, DEFAULT_LOCATIONS_PER_PAGE, DEFAULT_CALLS_PER_PAGE, type PaginationInfo, emptyCategoryForReason, failedAnchorEnvelope, emptyEnvelope, paginateItems, } from './semanticEnvelopes/envelopeHelpers.js';
+export { locationsEnvelope, referencesEnvelope, hoverEnvelope, buildReferencesByFile, normalizeHover, stringifyHoverPart, } from './semanticEnvelopes/locationEnvelopes.js';
+export { callsEnvelope, typeHierarchyEnvelope, } from './semanticEnvelopes/callEnvelopes.js';

package/dist/tools/lsp/semantic_content/semanticFileOps/anchor.d.ts

@@ -0,0 +1,24 @@
+import type { SemanticContentType, WorkspaceSymbolSemanticQuery } from '../../shared/semanticTypes.js';
+export declare function isNativeJsTsFile(uri: string): boolean;
+/**
+ * Throw when a real language server cannot answer a semantic operation. We do
+ * NOT fabricate a syntactic/same-file stand-in: a faked answer is worse than an
+ * honest failure because the agent would trust it. The thrown ToolError is
+ * routed by the execution boundary into the standard `status:"error"` envelope
+ * (errorCode `lspServerUnavailable`), and the message directs the agent to text
+ * search instead. documentSymbols/structural search keep their tree-sitter path
+ * and never reach here.
+ */
+export declare function throwLspUnavailable(uri: string, op: SemanticContentType): never;
+export declare function toLocalPath(value: string, workspaceRoot: string): string;
+export declare function workspaceSymbolAnchorExtensions(): string[];
+export declare function workspaceSymbolAnchorIncludeGlobs(): string[];
+export declare function findWorkspaceSymbolAnchorByName(query: WorkspaceSymbolSemanticQuery, workspaceRoot: string): Promise<string | undefined>;
+export declare function resolveWorkspaceSymbolAnchor(query: WorkspaceSymbolSemanticQuery, workspaceRoot: string): Promise<string>;
+export declare function lspErrorMessage(error: unknown): string;
+/**
+ * Native JS/TS document symbols via oxc, parsed into the LSP `DocumentSymbol[]`
+ * shape. Returns `null` when oxc declines the input so the caller can fall back
+ * to the "no symbols" empty state.
+ */
+export declare function nativeDocumentSymbols(uri: string, content: string): unknown[] | null;

package/dist/tools/lsp/semantic_content/semanticFileOps/documentSymbols.d.ts

@@ -0,0 +1,27 @@
+import type { LSPRange } from '@octocodeai/octocode-engine/lsp/types';
+import { type LspGetSemanticsQuery, type LspSemanticEnvelope } from '../../shared/semanticTypes.js';
+export type CompactSymbol = {
+    name: string;
+    kind: string;
+    line: number;
+    character: number;
+    endLine: number;
+    childCount: number;
+    containerName?: string;
+};
+type LspPositionLike = {
+    line: number;
+    character: number;
+};
+export declare function getDocumentSymbols(query: LspGetSemanticsQuery): Promise<LspSemanticEnvelope | Record<string, unknown>>;
+export declare function flattenDocumentSymbols(symbols: readonly unknown[]): CompactSymbol[];
+export declare function flattenDocumentSymbol(value: unknown, output: CompactSymbol[], containerName?: string): void;
+export declare function getSymbolRange(value: {
+    range?: unknown;
+    location?: unknown;
+}): LSPRange | undefined;
+export declare function isLspRange(value: unknown): value is LSPRange;
+export declare function isPosition(value: unknown): value is LspPositionLike;
+export declare function countTopLevelDocumentSymbols(symbols: readonly unknown[]): number;
+export declare function countBy<T>(items: readonly T[], keyForItem: (item: T) => string): Record<string, number>;
+export {};

package/dist/tools/lsp/semantic_content/semanticFileOps/workspaceSymbolsAndDiagnostics.d.ts

@@ -0,0 +1,20 @@
+import type { LspSemanticEnvelope, DiagnosticSemanticQuery, WorkspaceSymbolSemanticQuery } from '../../shared/semanticTypes.js';
+import type { CompactSymbol } from './documentSymbols.js';
+type CompactWorkspaceSymbol = CompactSymbol & {
+    uri: string;
+};
+type DiagnosticItem = {
+    severity?: number;
+    message: string;
+    line: number;
+    endLine: number;
+    character: number;
+    code?: string | number;
+    source?: string;
+};
+export declare function getWorkspaceSymbols(query: WorkspaceSymbolSemanticQuery): Promise<LspSemanticEnvelope | Record<string, unknown>>;
+export declare function compactWorkspaceSymbols(raw: unknown[]): CompactWorkspaceSymbol[];
+export declare function getFileDiagnostics(query: DiagnosticSemanticQuery): Promise<LspSemanticEnvelope | Record<string, unknown>>;
+export declare function extractDiagnostics(raw: unknown): DiagnosticItem[];
+export declare function parseDiagnostic(item: unknown): DiagnosticItem[];
+export {};

package/dist/tools/lsp/semantic_content/semanticFileOps.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Barrel for the semanticFileOps/ split (anchor & workspace resolution vs.
+ * documentSymbols vs. workspaceSymbols/diagnostics operations). Kept so no
+ * other file in the repo needs to change its import path.
+ */
+export { isNativeJsTsFile, throwLspUnavailable, toLocalPath, workspaceSymbolAnchorExtensions, workspaceSymbolAnchorIncludeGlobs, findWorkspaceSymbolAnchorByName, resolveWorkspaceSymbolAnchor, lspErrorMessage, nativeDocumentSymbols, } from './semanticFileOps/anchor.js';
+export { type CompactSymbol, getDocumentSymbols, flattenDocumentSymbols, flattenDocumentSymbol, getSymbolRange, isLspRange, isPosition, countTopLevelDocumentSymbols, countBy, } from './semanticFileOps/documentSymbols.js';
+export { getWorkspaceSymbols, compactWorkspaceSymbols, getFileDiagnostics, extractDiagnostics, parseDiagnostic, } from './semanticFileOps/workspaceSymbolsAndDiagnostics.js';

package/dist/tools/lsp/semantic_content/semanticPresentation.d.ts

@@ -0,0 +1,53 @@
+import type { CallHierarchyItem, IncomingCall, LSPRange, OutgoingCall } from '@octocodeai/octocode-engine/lsp/types';
+import { type CompactLocation, type LspGetSemanticsQuery, type LspSemanticEnvelope } from '../shared/semanticTypes.js';
+export type CompactCallTarget = {
+    name: string;
+    kind: string;
+    uri: string;
+    line: number;
+    endLine: number;
+    selectionLine?: number;
+};
+export type CompactCall = {
+    direction: 'incoming' | 'outgoing';
+    item: CompactCallTarget;
+    ranges: Array<{
+        line: number;
+        character: number;
+    }>;
+    rangeCount: number;
+    rangeSampleCount: number;
+    contentPreview?: string;
+};
+export declare function attachSemanticRawEvidence<T extends object>(result: T): T;
+export declare function formatSemanticResult(query: LspGetSemanticsQuery, result: LspSemanticEnvelope | Record<string, unknown>): LspSemanticEnvelope | Record<string, unknown>;
+export declare function withSemanticNext(result: LspSemanticEnvelope | Record<string, unknown>): LspSemanticEnvelope | Record<string, unknown>;
+export declare function isSemanticEnvelope(value: LspSemanticEnvelope | Record<string, unknown>): value is LspSemanticEnvelope;
+export declare function compactSemanticEnvelope(envelope: LspSemanticEnvelope): LspSemanticEnvelope;
+export declare function compactSemanticPayload(payload: LspSemanticEnvelope['payload']): LspSemanticEnvelope['payload'];
+export declare function formatSymbolRow(value: unknown): string;
+export declare function formatLocationRow(location: CompactLocation | string): string;
+export declare function formatReferenceFileRow(value: unknown): string;
+export declare function formatCallRow(value: unknown): string;
+export declare function formatCallTargetRow(value: unknown): string;
+export declare function formatRangeRow(value: unknown): string;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function stringField(record: Record<string, unknown>, key: string, fallback?: string): string;
+export declare function numberField(record: Record<string, unknown>, key: string, fallback?: number): number;
+export declare function arrayField(record: Record<string, unknown>, key: string): unknown[];
+export declare function oneLine(value: string, maxLength: number): string;
+export declare function compactIncomingCall(call: IncomingCall & {
+    direction: 'incoming';
+}, contextLines: number): CompactCall;
+export declare function compactOutgoingCall(call: OutgoingCall & {
+    direction: 'outgoing';
+}, contextLines: number): CompactCall;
+export declare function compactCallItem(item: CallHierarchyItem): CompactCallTarget;
+export declare function compactRanges(ranges: readonly LSPRange[]): {
+    line: number;
+    character: number;
+}[];
+export declare function contentPreview(item: CallHierarchyItem, contextLines: number): {
+    contentPreview?: string;
+};
+export declare function symbolKindName(kind: unknown): string;

package/dist/tools/lsp/shared/semanticTypes.d.ts

@@ -161,4 +161,10 @@ export type LspSemanticEnvelope = {
     pagination?: unknown;
     warnings?: string[];
     hints?: string[];
+    next?: Record<string, {
+        tool: string;
+        query: Record<string, unknown>;
+        why?: string;
+        confidence?: 'exact' | 'heuristic';
+    }>;
 };

package/dist/tools/package_search/execution.d.ts

@@ -2,6 +2,7 @@ import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { z } from 'zod';
 import type { NpmPackageQuerySchema } from '@octocodeai/octocode-core/schemas';
 type NpmSearchQuery = z.input<typeof NpmPackageQuerySchema>;
+import type { PackageResult } from '../../utils/package/common.js';
 import type { ToolExecutionArgs } from '../../types/execution.js';
 type PackageData = {
     name: string;
@@ -13,6 +14,12 @@ type PackageData = {
     repositoryDirectory?: string;
     repositoryId?: string;
     next?: Record<string, unknown>;
+    warnings?: string[];
+    diagnostics?: Array<{
+        level: 'info' | 'warning' | 'error';
+        message: string;
+        code?: string;
+    }>;
 };
 type PackageRepositoryData = {
     repository: string;
@@ -25,6 +32,7 @@ type CompactPackageData = {
     packages: PackageData[];
     repositories?: Record<string, PackageRepositoryData>;
 };
+export declare function formatPackageData(pkg: PackageResult): PackageData;
 export declare function compactPackageRepositories(packages: PackageData[]): CompactPackageData;
 type PackagePagination = {
     currentPage: number;

package/dist/tools/package_search/scheme.d.ts

@@ -25,14 +25,41 @@ export declare const NpmSearchOutputLocalSchema: z.ZodObject<{
                 repository: z.ZodOptional<z.ZodString>;
                 repositoryDirectory: z.ZodOptional<z.ZodString>;
                 repositoryId: z.ZodOptional<z.ZodString>;
-                next: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                next: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    tool: z.ZodString;
+                    query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                    why: z.ZodOptional<z.ZodString>;
+                    confidence: z.ZodOptional<z.ZodEnum<{
+                        exact: "exact";
+                        heuristic: "heuristic";
+                    }>>;
+                }, z.core.$strip>>>;
+                warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                diagnostics: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    level: z.ZodEnum<{
+                        error: "error";
+                        info: "info";
+                        warning: "warning";
+                    }>;
+                    message: z.ZodString;
+                    field: z.ZodOptional<z.ZodString>;
+                    code: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
             }, z.core.$loose>>>;
             repositories: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
                 repository: z.ZodString;
                 owner: z.ZodString;
                 repo: z.ZodString;
                 repositoryDirectory: z.ZodOptional<z.ZodString>;
-                next: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                next: z.ZodRecord<z.ZodString, z.ZodObject<{
+                    tool: z.ZodString;
+                    query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                    why: z.ZodOptional<z.ZodString>;
+                    confidence: z.ZodOptional<z.ZodEnum<{
+                        exact: "exact";
+                        heuristic: "heuristic";
+                    }>>;
+                }, z.core.$strip>>;
             }, z.core.$loose>>>;
             pagination: z.ZodOptional<z.ZodObject<{
                 currentPage: z.ZodNumber;
@@ -41,6 +68,20 @@ export declare const NpmSearchOutputLocalSchema: z.ZodObject<{
                 nextPage: z.ZodOptional<z.ZodNumber>;
                 pageSize: z.ZodOptional<z.ZodNumber>;
                 totalItems: z.ZodOptional<z.ZodNumber>;
+                perPage: z.ZodOptional<z.ZodNumber>;
+                totalFound: z.ZodOptional<z.ZodNumber>;
+                returned: z.ZodOptional<z.ZodNumber>;
+                totalMatches: z.ZodOptional<z.ZodNumber>;
+                reportedTotalMatches: z.ZodOptional<z.ZodNumber>;
+                reachableTotalMatches: z.ZodOptional<z.ZodNumber>;
+                totalMatchesKind: z.ZodOptional<z.ZodEnum<{
+                    exact: "exact";
+                    reported: "reported";
+                    lowerBound: "lowerBound";
+                }>>;
+                totalMatchesCapped: z.ZodOptional<z.ZodBoolean>;
+                totalResults: z.ZodOptional<z.ZodNumber>;
+                itemsPerPage: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
         }, z.core.$loose>>;
         status: z.ZodOptional<z.ZodString>;

package/dist/tools/providerMappers/codeSearch.d.ts

@@ -0,0 +1,66 @@
+import type { CodeSearchResult } from '../../providers/types.js';
+import type { z } from 'zod';
+import type { GitHubCodeSearchQuerySchema } from '@octocodeai/octocode-core/schemas';
+import type { WithOptionalMeta } from '../../types/execution.js';
+type GitHubCodeSearchQuery = z.infer<typeof GitHubCodeSearchQuerySchema>;
+/**
+ * Char-boundary truncation mirroring the Rust engine's `truncate_unicode`:
+ * keeps at most `maxChars` Unicode scalars and appends `...` when it cuts.
+ * Never slices UTF-8 mid-codepoint or mid-token — the single data-layer bound
+ * for GitHub code-search match fragments (the render layer must not re-trim).
+ */
+export declare function truncateSnippetChars(value: string, maxChars?: number): string;
+export declare function mapCodeSearchToolQuery(query: WithOptionalMeta<GitHubCodeSearchQuery>): {
+    keywords: string[];
+    projectId: string;
+    owner: string;
+    path: string;
+    filename: string;
+    extension: string;
+    language: string | undefined;
+    match: "file" | "path";
+    limit: number | undefined;
+    page: number;
+    mainResearchGoal: string;
+    researchGoal: string;
+    reasoning: string;
+};
+export interface CodeSearchGroupedMatch {
+    path: string;
+    value?: string;
+    pathOnly?: boolean;
+    matchIndices?: Array<{
+        start: number;
+        end: number;
+        lineOffset: number;
+    }>;
+    url?: string;
+}
+export interface CodeSearchGroupedResult {
+    id: string;
+    queryId?: string;
+    owner: string;
+    repo: string;
+    matches: CodeSearchGroupedMatch[];
+}
+export interface CodeSearchPagination {
+    currentPage: number;
+    totalPages: number;
+    perPage: number;
+    totalMatches: number;
+    reportedTotalMatches?: number;
+    reachableTotalMatches?: number;
+    totalMatchesKind?: 'exact' | 'reported' | 'lowerBound';
+    totalMatchesCapped?: boolean;
+    hasMore: boolean;
+    nextPage?: number;
+    uniqueFileCount?: number;
+}
+export interface CodeSearchFlatResult {
+    results: CodeSearchGroupedResult[];
+    pagination?: CodeSearchPagination;
+    nonExistentScope?: boolean;
+    incompleteResults?: boolean;
+}
+export declare function mapCodeSearchProviderResult(data: CodeSearchResult, query: WithOptionalMeta<GitHubCodeSearchQuery>): CodeSearchFlatResult;
+export {};

package/dist/tools/providerMappers/fileContent.d.ts

@@ -0,0 +1,28 @@
+import type { FileContentResult as ProviderFileContentResult } from '../../providers/types.js';
+import type { z } from 'zod';
+import type { WithOptionalMeta } from '../../types/execution.js';
+import { FileContentQueryLocalSchema } from '../github_fetch_content/scheme.js';
+type LocalFileContentQuery = z.infer<typeof FileContentQueryLocalSchema> & {
+    minify: import('../../scheme/fields.js').MinifyMode;
+};
+export declare function mapFileContentToolQuery(query: LocalFileContentQuery): {
+    projectId: string;
+    path: string;
+    ref: string;
+    startLine: number;
+    endLine: number;
+    matchString: string;
+    contextLines: number;
+    fullContent: boolean;
+    forceRefresh: boolean;
+    charOffset: number;
+    charLength: number;
+    minify: "none" | "standard" | "symbols";
+    matchStringIsRegex: boolean;
+    matchStringCaseSensitive: boolean;
+    mainResearchGoal: string;
+    researchGoal: string;
+    reasoning: string;
+};
+export declare function mapFileContentProviderResult(data: ProviderFileContentResult, query: WithOptionalMeta<LocalFileContentQuery>): Record<string, unknown>;
+export {};

package/dist/tools/providerMappers/pullRequests.d.ts

@@ -0,0 +1,158 @@
+import type { PullRequestSearchResult as ProviderPullRequestSearchResult } from '../../providers/types.js';
+import type { z } from 'zod';
+import type { GitHubPullRequestSearchQueryLocalSchema } from '../github_search_pull_requests/scheme.js';
+import type { WithOptionalMeta } from '../../types/execution.js';
+type GitHubPullRequestSearchQuery = z.infer<typeof GitHubPullRequestSearchQueryLocalSchema>;
+type PRDefaultKeys = 'order' | 'limit' | 'page';
+type PartialPRQuery = WithOptionalMeta<Omit<GitHubPullRequestSearchQuery, PRDefaultKeys> & Partial<Pick<GitHubPullRequestSearchQuery, PRDefaultKeys>>>;
+export declare function mapPullRequestToolQuery(query: PartialPRQuery): {
+    projectId: string;
+    owner: string;
+    query: string;
+    number: number;
+    state: "open" | "closed" | "merged" | "all" | undefined;
+    author: string;
+    assignee: string;
+    commenter: string;
+    involves: string;
+    mentions: string;
+    reviewRequested: string;
+    reviewedBy: string;
+    labels: string[];
+    noLabel: boolean;
+    noMilestone: boolean;
+    noProject: boolean;
+    noAssignee: boolean;
+    baseBranch: string;
+    headBranch: string;
+    created: string;
+    updated: string;
+    closed: string;
+    mergedAt: string;
+    comments: string;
+    reactions: string;
+    interactions: string;
+    draft: boolean;
+    match: ("title" | "body" | "comments")[];
+    milestone: string;
+    language: string;
+    checks: "success" | "failure" | "pending";
+    review: "none" | "approved" | "changes_requested" | "required";
+    locked: boolean;
+    visibility: "public" | "private";
+    teamMentions: string;
+    project: string;
+    archived: boolean | undefined;
+    content: unknown;
+    reviewMode: "full" | "summary";
+    filePage: number;
+    commentPage: number;
+    commitPage: number;
+    itemsPerPage: number;
+    sort: "created" | "updated" | "best-match" | "comments" | "reactions" | undefined;
+    order: "asc" | "desc" | undefined;
+    limit: number;
+    page: number;
+    charOffset: number;
+    charLength: number;
+    mainResearchGoal: string;
+    researchGoal: string;
+    reasoning: string;
+};
+export declare function mapPullRequestProviderResultData(data: ProviderPullRequestSearchResult, options?: {
+    includeFileChanges?: boolean;
+}): {
+    pullRequests: {
+        sanitizationWarnings?: string[];
+        fileChanges?: {
+            path: string;
+            status: string;
+            additions: number;
+            deletions: number;
+            patch?: string;
+        }[];
+        reviewSummary: {
+            totalComments: number;
+            inlineComments: number;
+            discussionComments: number;
+            commenters: string[];
+            latestCommentAt?: string;
+            themes: string[];
+        };
+        commits: {
+            sha: string;
+            message: string;
+            author: string;
+            date: string;
+        }[];
+        reviews: {
+            id: string;
+            user: string;
+            state: string;
+            body: string;
+            submittedAt?: string;
+            commitId?: string;
+        }[];
+        comments: {
+            bodyPagination: {
+                charOffset: number;
+                charLength: number;
+                totalChars: number;
+                hasMore: boolean;
+                nextCharOffset?: number;
+            };
+            id: string;
+            author: string;
+            body: string;
+            createdAt: string;
+            updatedAt: string;
+            commentType?: "discussion" | "review_inline";
+            path?: string;
+            line?: number;
+            in_reply_to_id?: number;
+        }[];
+        url: string;
+        state: "open" | "closed" | "merged";
+        draft: boolean;
+        author: string;
+        assignees: string[];
+        labels: string[];
+        sourceBranch: string;
+        targetBranch: string;
+        sourceSha: string;
+        targetSha: string;
+        createdAt: string;
+        updatedAt: string;
+        closedAt: string;
+        mergedAt: string;
+        commentsCount: number;
+        changedFilesCount: number;
+        additions: number;
+        deletions: number;
+        bodyPagination: {
+            charOffset: number;
+            charLength: number;
+            totalChars: number;
+            hasMore: boolean;
+            nextCharOffset?: number;
+        };
+        number: number;
+        title: string;
+        body: string;
+    }[];
+    resultData: Record<string, unknown>;
+    pagination: {
+        nextPage?: number;
+        hasMore: boolean;
+        uniqueFileCount?: number;
+        totalMatchesCapped?: boolean;
+        totalMatchesKind?: "exact" | "reported" | "lowerBound";
+        reachableTotalMatches?: number;
+        reportedTotalMatches?: number;
+        totalMatches?: number;
+        currentPage: number;
+        totalPages: number;
+        perPage: number;
+    };
+};
+export {};