@mcoda/codali 0.1.108 → 0.1.109

package/dist/gateway/RelevanceJudge.js

@@ -0,0 +1,87 @@
+/**
+ * Decides whether local search results actually answer the question.
+ *
+ * The alternative approaches are both worse:
+ *
+ * - **Score thresholds** do not discriminate. Measured against this repository,
+ *   "GDP of France 2025" scores 29.07 while "gateway planner class" scores
+ *   14.35 — the irrelevant query scores higher, because a test fixture contains
+ *   the phrase. Any threshold would be arbitrary and frequently wrong.
+ * - **Keyword rules** ("if the query mentions GDP or news, go to the web") are
+ *   precisely the hardcoding this project rules out: they work for the examples
+ *   someone thought of and fail on the next question.
+ *
+ * A model reading the titles is generic and costs one short call. It is asked
+ * for a single token so a small local model can answer it quickly.
+ */
+const MAX_TITLES = 8;
+const MAX_TITLE_CHARS = 90;
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+/**
+ * Reduces a result payload to a short list of titles. The judge needs to know
+ * *what* was found, not the contents — sending snippets would cost more than
+ * the web call being avoided.
+ */
+export const summarizeResultTitles = (results) => {
+    if (!isRecord(results))
+        return [];
+    const hits = ["hits", "results", "matches"]
+        .map((key) => results[key])
+        .find((value) => Array.isArray(value) && value.length > 0);
+    if (!hits)
+        return [];
+    const titles = [];
+    for (const hit of hits.slice(0, MAX_TITLES)) {
+        if (!isRecord(hit))
+            continue;
+        const title = (typeof hit.rel_path === "string" && hit.rel_path) ||
+            (typeof hit.relPath === "string" && hit.relPath) ||
+            (typeof hit.path === "string" && hit.path) ||
+            (typeof hit.title === "string" && hit.title) ||
+            (typeof hit.url === "string" && hit.url) ||
+            (typeof hit.doc_id === "string" && hit.doc_id) ||
+            "";
+        if (title)
+            titles.push(String(title).slice(0, MAX_TITLE_CHARS));
+    }
+    return titles;
+};
+export const createRelevanceJudge = (options) => async ({ query, results }) => {
+    const titles = summarizeResultTitles(results);
+    // Nothing to judge; the caller's presence check already decided.
+    if (titles.length === 0)
+        return true;
+    const response = await options.provider.generate({
+        messages: [
+            {
+                role: "system",
+                content: [
+                    "You decide whether local search results are relevant to a question.",
+                    "You are shown only the titles or file paths that were found.",
+                    "Answer with exactly one word: YES if these look like they could answer the question, NO if they are about something else.",
+                    "A repository file that merely happens to mention a word from the question is NO.",
+                ].join("\n"),
+            },
+            {
+                role: "user",
+                content: [
+                    `Question: ${query}`,
+                    "",
+                    "Results found locally:",
+                    ...titles.map((title) => `- ${title}`),
+                    "",
+                    "Could these answer the question? Reply YES or NO.",
+                ].join("\n"),
+            },
+        ],
+        toolChoice: "none",
+        maxTokens: options.maxTokens ?? 5,
+        temperature: 0,
+    });
+    const verdict = response.message.content.trim().toUpperCase();
+    // Default to keeping the local result when the answer is unreadable: a
+    // needless web call is a worse failure than a slightly weak local hit.
+    if (verdict.startsWith("NO"))
+        return false;
+    return true;
+};

package/dist/gateway/ResponseSchema.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Enforcement for `CodaliGatewayRequest.response.schema`.
+ *
+ * The field has been part of the request contract for a while but was never
+ * validated — only `response.format === "json"` was read, so a caller could ask
+ * for a schema and receive anything at all. That pushes parsing and correction
+ * logic into every consuming product, which is precisely the duplication Codali
+ * exists to remove.
+ *
+ * Validation reuses the same structural rules as tool-argument validation so a
+ * schema behaves identically whether it describes a tool input or a response.
+ */
+export interface ResponseSchemaViolation {
+    path: string;
+    message: string;
+}
+export interface ResponseSchemaValidation {
+    ok: boolean;
+    value?: unknown;
+    violations: ResponseSchemaViolation[];
+}
+/**
+ * Extracts a JSON value from a model response. Models routinely wrap JSON in
+ * prose or a fenced block even when told not to, and rejecting those outright
+ * would burn a repair attempt on a formatting quirk rather than a real
+ * structural failure.
+ */
+export declare const extractJsonPayload: (content: string) => unknown;
+export declare const validateResponseAgainstSchema: (content: string, schema: Record<string, unknown> | undefined) => ResponseSchemaValidation;
+/** Human-readable violation list, used to prompt one repair attempt. */
+export declare const describeViolations: (violations: ResponseSchemaViolation[]) => string;
+//# sourceMappingURL=ResponseSchema.d.ts.map

package/dist/gateway/ResponseSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResponseSchema.d.ts","sourceRoot":"","sources":["../../src/gateway/ResponseSchema.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,uBAAuB,EAAE,CAAC;CACvC;AAwED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG,OAuBpD,CAAC;AAUF,eAAO,MAAM,6BAA6B,GACxC,SAAS,MAAM,EACf,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAC1C,wBAmBF,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,GAAI,YAAY,uBAAuB,EAAE,KAAG,MACY,CAAC"}

package/dist/gateway/ResponseSchema.js

@@ -0,0 +1,120 @@
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const typeOf = (value) => {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "integer" : "number";
+    return typeof value;
+};
+const typeMatches = (value, expected) => {
+    const actual = typeOf(value);
+    if (expected === actual)
+        return true;
+    // An integer satisfies "number"; a whole float satisfies "integer".
+    if (expected === "number" && actual === "integer")
+        return true;
+    if (expected === "integer" && actual === "number")
+        return Number.isInteger(value);
+    return false;
+};
+const validateAgainst = (value, schema, path, violations) => {
+    const expectedTypes = schema.type
+        ? (Array.isArray(schema.type) ? schema.type : [schema.type])
+        : undefined;
+    if (expectedTypes && !expectedTypes.some((type) => typeMatches(value, type))) {
+        violations.push({
+            path,
+            message: `expected ${expectedTypes.join(" or ")}, received ${typeOf(value)}`,
+        });
+        return;
+    }
+    if (schema.enum && !schema.enum.some((entry) => entry === value)) {
+        violations.push({
+            path,
+            message: `value is not one of ${JSON.stringify(schema.enum)}`,
+        });
+        return;
+    }
+    if (Array.isArray(value) && schema.items) {
+        value.forEach((entry, index) => {
+            validateAgainst(entry, schema.items, `${path}[${index}]`, violations);
+        });
+        return;
+    }
+    if (isRecord(value)) {
+        for (const key of schema.required ?? []) {
+            if (!(key in value)) {
+                violations.push({ path: `${path}.${key}`, message: "required property is missing" });
+            }
+        }
+        const properties = schema.properties ?? {};
+        for (const [key, entry] of Object.entries(value)) {
+            const child = properties[key];
+            if (child) {
+                validateAgainst(entry, child, `${path}.${key}`, violations);
+            }
+            else if (schema.additionalProperties === false) {
+                violations.push({ path: `${path}.${key}`, message: "unexpected property" });
+            }
+        }
+    }
+};
+/**
+ * Extracts a JSON value from a model response. Models routinely wrap JSON in
+ * prose or a fenced block even when told not to, and rejecting those outright
+ * would burn a repair attempt on a formatting quirk rather than a real
+ * structural failure.
+ */
+export const extractJsonPayload = (content) => {
+    const trimmed = content.trim();
+    if (!trimmed)
+        return undefined;
+    const direct = tryParse(trimmed);
+    if (direct !== undefined)
+        return direct;
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fenced?.[1]) {
+        const parsed = tryParse(fenced[1].trim());
+        if (parsed !== undefined)
+            return parsed;
+    }
+    const firstBrace = trimmed.search(/[[{]/);
+    if (firstBrace >= 0) {
+        const lastBrace = Math.max(trimmed.lastIndexOf("}"), trimmed.lastIndexOf("]"));
+        if (lastBrace > firstBrace) {
+            const parsed = tryParse(trimmed.slice(firstBrace, lastBrace + 1));
+            if (parsed !== undefined)
+                return parsed;
+        }
+    }
+    return undefined;
+};
+const tryParse = (value) => {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+};
+export const validateResponseAgainstSchema = (content, schema) => {
+    if (!schema) {
+        return { ok: true, value: content, violations: [] };
+    }
+    const payload = extractJsonPayload(content);
+    if (payload === undefined) {
+        return {
+            ok: false,
+            violations: [{ path: "$", message: "response was not parseable as JSON" }],
+        };
+    }
+    const violations = [];
+    validateAgainst(payload, schema, "$", violations);
+    return violations.length === 0
+        ? { ok: true, value: payload, violations: [] }
+        : { ok: false, value: payload, violations };
+};
+/** Human-readable violation list, used to prompt one repair attempt. */
+export const describeViolations = (violations) => violations.map((violation) => `- ${violation.path}: ${violation.message}`).join("\n");

package/dist/gateway/TemporalContext.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Resolves relative time expressions to absolute ranges at plan time.
+ *
+ * "How is Bekir's performance going for the last two weeks?" is only answerable
+ * if every worker agrees on what "the last two weeks" means. Left to the model,
+ * each task invents its own window, connector queries disagree, and the run is
+ * unreproducible — re-running tomorrow silently asks a different question.
+ *
+ * So the range is computed once, in code, stamped into the trace, and handed to
+ * the planner as a fact. Resolution is deliberately conservative: an expression
+ * that cannot be resolved unambiguously is left alone rather than guessed at.
+ */
+export interface AbsoluteRange {
+    /** Inclusive ISO-8601 start instant. */
+    since: string;
+    /** Exclusive ISO-8601 end instant. */
+    until: string;
+    /** The phrase this range was derived from. */
+    phrase: string;
+    days: number;
+}
+export interface TemporalContext {
+    /** The instant the run treats as "now". */
+    now: string;
+    range?: AbsoluteRange;
+}
+/**
+ * Extracts an absolute range from a query. Returns undefined when the query
+ * contains no relative time expression, or one we cannot resolve confidently —
+ * a wrong window is worse than no window, because it looks authoritative.
+ */
+export declare const resolveRelativeRange: (query: string, now?: Date) => AbsoluteRange | undefined;
+export declare const buildTemporalContext: (query: string, now?: Date) => TemporalContext;
+/** The lines handed to the planner so every task shares one window. */
+export declare const renderTemporalContext: (context: TemporalContext) => string[];
+//# sourceMappingURL=TemporalContext.d.ts.map

package/dist/gateway/TemporalContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemporalContext.d.ts","sourceRoot":"","sources":["../../src/gateway/TemporalContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AA2DD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,OAAO,MAAM,EACb,MAAK,IAAiB,KACrB,aAAa,GAAG,SA6BlB,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,OAAO,MAAM,EACb,MAAK,IAAiB,KACrB,eAGD,CAAC;AAEH,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,GAAI,SAAS,eAAe,KAAG,MAAM,EAiBtE,CAAC"}

package/dist/gateway/TemporalContext.js

@@ -0,0 +1,115 @@
+/**
+ * Resolves relative time expressions to absolute ranges at plan time.
+ *
+ * "How is Bekir's performance going for the last two weeks?" is only answerable
+ * if every worker agrees on what "the last two weeks" means. Left to the model,
+ * each task invents its own window, connector queries disagree, and the run is
+ * unreproducible — re-running tomorrow silently asks a different question.
+ *
+ * So the range is computed once, in code, stamped into the trace, and handed to
+ * the planner as a fact. Resolution is deliberately conservative: an expression
+ * that cannot be resolved unambiguously is left alone rather than guessed at.
+ */
+const DAY_MS = 86400000;
+const WORD_NUMBERS = {
+    one: 1,
+    two: 2,
+    three: 3,
+    four: 4,
+    five: 5,
+    six: 6,
+    seven: 7,
+    eight: 8,
+    nine: 9,
+    ten: 10,
+    a: 1,
+    an: 1,
+};
+const UNIT_DAYS = {
+    day: 1,
+    days: 1,
+    week: 7,
+    weeks: 7,
+    month: 30,
+    months: 30,
+    quarter: 91,
+    quarters: 91,
+    year: 365,
+    years: 365,
+};
+/** Fixed phrases with no quantity, e.g. "yesterday". */
+const FIXED_PHRASES = [
+    { pattern: /\byesterday\b/i, days: 1 },
+    { pattern: /\btoday\b/i, days: 1 },
+    { pattern: /\bthis week\b/i, days: 7 },
+    { pattern: /\blast week\b/i, days: 7 },
+    { pattern: /\bthis month\b/i, days: 30 },
+    { pattern: /\blast month\b/i, days: 30 },
+    { pattern: /\bthis quarter\b/i, days: 91 },
+    { pattern: /\blast quarter\b/i, days: 91 },
+    { pattern: /\bthis year\b/i, days: 365 },
+    { pattern: /\blast year\b/i, days: 365 },
+    { pattern: /\brecently\b/i, days: 14 },
+];
+/**
+ * Matches "last two weeks", "past 30 days", "previous 3 months".
+ * The quantity may be digits or a small word number.
+ */
+const QUANTIFIED = /\b(?:last|past|previous|recent)\s+(\d{1,3}|[a-z]+)\s+(day|days|week|weeks|month|months|quarter|quarters|year|years)\b/i;
+const parseQuantity = (raw) => {
+    const numeric = Number.parseInt(raw, 10);
+    if (Number.isFinite(numeric) && numeric > 0 && numeric <= 999)
+        return numeric;
+    return WORD_NUMBERS[raw.toLowerCase()];
+};
+/**
+ * Extracts an absolute range from a query. Returns undefined when the query
+ * contains no relative time expression, or one we cannot resolve confidently —
+ * a wrong window is worse than no window, because it looks authoritative.
+ */
+export const resolveRelativeRange = (query, now = new Date()) => {
+    const quantified = query.match(QUANTIFIED);
+    if (quantified) {
+        const quantity = parseQuantity(quantified[1] ?? "");
+        const unitDays = UNIT_DAYS[(quantified[2] ?? "").toLowerCase()];
+        if (quantity && unitDays) {
+            const days = quantity * unitDays;
+            return {
+                since: new Date(now.getTime() - days * DAY_MS).toISOString(),
+                until: now.toISOString(),
+                phrase: quantified[0],
+                days,
+            };
+        }
+    }
+    for (const fixed of FIXED_PHRASES) {
+        const match = query.match(fixed.pattern);
+        if (match) {
+            return {
+                since: new Date(now.getTime() - fixed.days * DAY_MS).toISOString(),
+                until: now.toISOString(),
+                phrase: match[0],
+                days: fixed.days,
+            };
+        }
+    }
+    return undefined;
+};
+export const buildTemporalContext = (query, now = new Date()) => ({
+    now: now.toISOString(),
+    range: resolveRelativeRange(query, now),
+});
+/** The lines handed to the planner so every task shares one window. */
+export const renderTemporalContext = (context) => {
+    const lines = [`Current time: ${context.now}`];
+    if (context.range) {
+        lines.push(`Resolved time range for "${context.range.phrase}": ${context.range.since} to ${context.range.until} (${context.range.days} days).`, "Use these absolute timestamps in every tool call. Do not compute your own dates.");
+    }
+    else {
+        // Stating the current time invites a model to use it as a range start,
+        // which asks for everything since this instant and returns nothing.
+        // Observed: `list_commits since=<now>`, a valid call with an empty answer.
+        lines.push("The question named no time period. Do not use the current time as a start or end date — that would match nothing.", "Omit date filters entirely and let the tool return its most recent results.");
+    }
+    return lines;
+};

package/dist/gateway/ToolCapabilityCompiler.d.ts

@@ -26,6 +26,11 @@ export interface CodaliGatewayCompiledToolCapability {
 }
 export interface ToolCapabilityCompilerInput {
     policy: CodaliGatewayPolicy;
+    /**
+     * Tools whose read-only status has been declared by policy rather than
+     * inferred from their name. See {@link classifyCapabilityRisk}.
+     */
+    declaredReadOnlyTools?: string[];
     docdex?: CodaliRuntimeDocdexInput;
     tools?: CodaliRuntimeToolManifest;
     requiredDocdexOperations?: string[];

package/dist/gateway/ToolCapabilityCompiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToolCapabilityCompiler.d.ts","sourceRoot":"","sources":["../../src/gateway/ToolCapabilityCompiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,4BAA4B,EAE5B,mCAAmC,EACnC,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EACV,mBAAmB,EACnB,6BAA6B,EAC9B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,+BAA+B,GACvC,QAAQ,GACR,SAAS,GACT,cAAc,GACd,aAAa,GACb,SAAS,CAAC;AAEd,MAAM,MAAM,iCAAiC,GACzC,SAAS,GACT,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,mCAAmC;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,+BAA+B,CAAC;IACtC,MAAM,EAAE,iCAAiC,CAAC;IAC1C,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,6BAA6B,CAAC;IAC5C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,KAAK,CAAC,EAAE,yBAAyB,CAAC;IAClC,wBAAwB,CAAC,EAAE,MAAM,EAAE,CAAC;IACpC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,4BAA4B,CAAC,CAAC;IAC/D,cAAc,CAAC,EAAE,mCAAmC,CAAC;IACrD,YAAY,EAAE,mCAAmC,EAAE,CAAC;IACpD,YAAY,EAAE,wBAAwB,EAAE,CAAC;IACzC,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,MAAM,EAAE,0BAA0B,EAAE,CAAC;IACrC,wBAAwB,EAAE,MAAM,EAAE,CAAC;CACpC;AAED,eAAO,MAAM,sCAAsC,iHAOzC,CAAC;AAEX,eAAO,MAAM,qCAAqC,mMAgBxC,CAAC;AAqVX,eAAO,MAAM,uBAAuB,GAClC,OAAO,2BAA2B,KACjC,yBAkRF,CAAC"}
+{"version":3,"file":"ToolCapabilityCompiler.d.ts","sourceRoot":"","sources":["../../src/gateway/ToolCapabilityCompiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,4BAA4B,EAE5B,mCAAmC,EACnC,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EACV,mBAAmB,EACnB,6BAA6B,EAC9B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,+BAA+B,GACvC,QAAQ,GACR,SAAS,GACT,cAAc,GACd,aAAa,GACb,SAAS,CAAC;AAEd,MAAM,MAAM,iCAAiC,GACzC,SAAS,GACT,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,mCAAmC;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,+BAA+B,CAAC;IACtC,MAAM,EAAE,iCAAiC,CAAC;IAC1C,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,6BAA6B,CAAC;IAC5C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,mBAAmB,CAAC;IAC5B;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,KAAK,CAAC,EAAE,yBAAyB,CAAC;IAClC,wBAAwB,CAAC,EAAE,MAAM,EAAE,CAAC;IACpC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,4BAA4B,CAAC,CAAC;IAC/D,cAAc,CAAC,EAAE,mCAAmC,CAAC;IACrD,YAAY,EAAE,mCAAmC,EAAE,CAAC;IACpD,YAAY,EAAE,wBAAwB,EAAE,CAAC;IACzC,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,MAAM,EAAE,0BAA0B,EAAE,CAAC;IACrC,wBAAwB,EAAE,MAAM,EAAE,CAAC;CACpC;AAED,eAAO,MAAM,sCAAsC,iHAOzC,CAAC;AAEX,eAAO,MAAM,qCAAqC,mMAgBxC,CAAC;AAwWX,eAAO,MAAM,uBAAuB,GAClC,OAAO,2BAA2B,KACjC,yBAgSF,CAAC"}

package/dist/gateway/ToolCapabilityCompiler.js

@@ -91,10 +91,28 @@ const hasRiskToken = (tool, tokens) => {
     return toolNameTokens(tool).some((token) => tokens.has(token)) ||
         [...tokens].some((token) => normalized === token || normalized.endsWith(`_${token}`));
 };
-const classifyCapabilityRisk = (name, readOnly) => {
+/**
+ * Classifies a tool's risk.
+ *
+ * The name heuristic exists because, before connectors, a tool's name was the
+ * only signal available. It cannot distinguish "get a commit" from "commit
+ * something": `get_commit` ends with `_commit` and was therefore classified as
+ * a write, which blocked an ordinary read.
+ *
+ * A tool whose read-only status has been *declared* — an operator marking an
+ * MCP server read-only, or an HTTP tool restricted to GET/HEAD — carries better
+ * information than its name, so the declaration wins.
+ *
+ * The destructive check is not overridable. A declaration that `delete_file` is
+ * read-only is a configuration mistake, and the floor should hold against it.
+ */
+const classifyCapabilityRisk = (name, readOnly, declaredReadOnly = false) => {
     if (hasRiskToken(name, DESTRUCTIVE_TOOL_TOKENS)) {
         return "destructive_blocked";
     }
+    if (declaredReadOnly && readOnly) {
+        return "read_only";
+    }
     if (!readOnly || hasRiskToken(name, WRITE_TOOL_TOKENS)) {
         return "write_with_approval";
     }
@@ -268,8 +286,15 @@ export const compileToolCapabilities = (input) => {
     const contracts = normalizeAppToolContracts(input.policy.appToolContracts, warnings);
     const allowedBackingTools = new Set(unique(input.allowedBackingTools ?? CODALI_GATEWAY_READ_ONLY_BACKING_TOOLS));
     const requiredDocdexOperations = new Set(unique(input.requiredDocdexOperations ?? []));
+    const declaredReadOnly = new Set(unique([
+        ...(input.declaredReadOnlyTools ?? []),
+        ...readManifestTools(input.tools ?? input.docdex?.toolManifest, [
+            "readOnlyTools",
+            "read_only_tools",
+        ]),
+    ]));
     const addCapability = (name, kind, status, readOnly, backingTools, reasons) => {
-        const riskCategory = classifyCapabilityRisk(name, readOnly);
+        const riskCategory = classifyCapabilityRisk(name, readOnly, declaredReadOnly.has(name));
         capabilities.push({
             name,
             kind,

package/dist/gateway/ToolDescriptorSource.d.ts

@@ -0,0 +1,6 @@
+import type { ToolRegistry } from "../tools/ToolRegistry.js";
+import type { ToolDefinition } from "../tools/ToolTypes.js";
+import type { CodaliGatewayPlannerToolDescriptor } from "./GatewayPlanner.js";
+export declare const gatewayToolDescriptorsFromDefinitions: (tools: readonly ToolDefinition[]) => Record<string, CodaliGatewayPlannerToolDescriptor>;
+export declare const gatewayToolDescriptorsFromRegistry: (registry: ToolRegistry, names?: readonly string[]) => Record<string, CodaliGatewayPlannerToolDescriptor>;
+//# sourceMappingURL=ToolDescriptorSource.d.ts.map

package/dist/gateway/ToolDescriptorSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolDescriptorSource.d.ts","sourceRoot":"","sources":["../../src/gateway/ToolDescriptorSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,uBAAuB,CAAC;AAE5E,OAAO,KAAK,EAAE,kCAAkC,EAAE,MAAM,qBAAqB,CAAC;AAqB9E,eAAO,MAAM,qCAAqC,GAChD,OAAO,SAAS,cAAc,EAAE,KAC/B,MAAM,CAAC,MAAM,EAAE,kCAAkC,CAMnD,CAAC;AAEF,eAAO,MAAM,kCAAkC,GAC7C,UAAU,YAAY,EACtB,QAAQ,SAAS,MAAM,EAAE,KACxB,MAAM,CAAC,MAAM,EAAE,kCAAkC,CAMnD,CAAC"}

package/dist/gateway/ToolDescriptorSource.js

@@ -0,0 +1,30 @@
+import { toolDescriptorFor } from "../tools/ToolRegistry.js";
+/**
+ * Bridges the executor's tool registry to the planner's model-facing view.
+ *
+ * This exists so there is exactly one place where a tool's schema is turned
+ * into something a model reads. If the planner and the executor ever disagree
+ * about a tool's arguments, it is because something bypassed this function.
+ */
+const toPlannerDescriptor = (descriptor) => ({
+    name: descriptor.name,
+    description: descriptor.description,
+    inputSchema: descriptor.inputSchema,
+    outputSchema: descriptor.outputSchema,
+    capability: descriptor.capability,
+    readOnly: descriptor.readOnly,
+});
+export const gatewayToolDescriptorsFromDefinitions = (tools) => {
+    const descriptors = {};
+    for (const tool of tools) {
+        descriptors[tool.name] = toPlannerDescriptor(toolDescriptorFor(tool));
+    }
+    return descriptors;
+};
+export const gatewayToolDescriptorsFromRegistry = (registry, names) => {
+    const descriptors = {};
+    for (const descriptor of registry.catalog(names)) {
+        descriptors[descriptor.name] = toPlannerDescriptor(descriptor);
+    }
+    return descriptors;
+};

package/dist/gateway/ToolExposure.d.ts

@@ -0,0 +1,36 @@
+import type { CodaliGatewayPlannerToolDescriptor } from "./GatewayPlanner.js";
+/** Cap on tools expanded in one planner prompt, after capability narrowing. */
+export declare const MAX_EXPANDED_TOOLS = 40;
+export interface ToolExposureDescriptor extends CodaliGatewayPlannerToolDescriptor {
+    capability?: string;
+    readOnly?: boolean;
+}
+export type ToolExposureDescriptors = Record<string, string | ToolExposureDescriptor>;
+interface NormalizedDescriptor {
+    name: string;
+    description: string;
+    capability: string;
+    readOnly: boolean;
+    inputSchema?: Record<string, unknown>;
+}
+export declare const normalizeToolExposure: (toolNames: readonly string[], descriptors: ToolExposureDescriptors | undefined) => NormalizedDescriptor[];
+export declare const groupByCapability: (tools: NormalizedDescriptor[]) => Map<string, NormalizedDescriptor[]>;
+/**
+ * Stage 1 rendering: one line per capability, no schemas. This is what the
+ * classifier sees, and it stays a fixed small size no matter how many tools a
+ * tenant has connected.
+ */
+export declare const renderCapabilityLines: (toolNames: readonly string[], descriptors: ToolExposureDescriptors | undefined) => string;
+export interface RenderToolLinesResult {
+    text: string;
+    expandedTools: string[];
+    truncated: boolean;
+}
+/**
+ * Stage 2 rendering: full descriptions and argument shapes, narrowed to the
+ * capabilities the classifier selected. Passing no selection expands
+ * everything, which is the correct behaviour for small local tool sets.
+ */
+export declare const renderToolLines: (toolNames: readonly string[], descriptors: ToolExposureDescriptors | undefined, selectedCapabilities?: readonly string[]) => RenderToolLinesResult;
+export {};
+//# sourceMappingURL=ToolExposure.d.ts.map

package/dist/gateway/ToolExposure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolExposure.d.ts","sourceRoot":"","sources":["../../src/gateway/ToolExposure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kCAAkC,EAAE,MAAM,qBAAqB,CAAC;AAuB9E,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,MAAM,WAAW,sBAAuB,SAAQ,kCAAkC;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAC1C,MAAM,EACN,MAAM,GAAG,sBAAsB,CAChC,CAAC;AAEF,UAAU,oBAAoB;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAwDD,eAAO,MAAM,qBAAqB,GAChC,WAAW,SAAS,MAAM,EAAE,EAC5B,aAAa,uBAAuB,GAAG,SAAS,KAC/C,oBAAoB,EACwC,CAAC;AAEhE,eAAO,MAAM,iBAAiB,GAC5B,OAAO,oBAAoB,EAAE,KAC5B,GAAG,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAQpC,CAAC;AAeF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAChC,WAAW,SAAS,MAAM,EAAE,EAC5B,aAAa,uBAAuB,GAAG,SAAS,KAC/C,MAUF,CAAC;AAqBF,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC1B,WAAW,SAAS,MAAM,EAAE,EAC5B,aAAa,uBAAuB,GAAG,SAAS,EAChD,uBAAuB,SAAS,MAAM,EAAE,KACvC,qBA+BF,CAAC"}