@inferior-ai/sdk 2.0.0-beta.3

package/dist/client.js

@@ -0,0 +1,900 @@
+/**
+ * Inferior TypeScript SDK client.
+ *
+ * Async-first HTTP client for the Inferior REST API. Mirrors the Python SDK
+ * exactly — same methods, same parameters, same response types.
+ *
+ * @example
+ * ```typescript
+ * import { InferiorClient } from '@inferior-ai/sdk'
+ *
+ * const client = new InferiorClient({ apiKey: 'cw_full_...' })
+ * const response = await client.search('stripe webhook timeout')
+ * console.log(response.results[0].title)
+ * ```
+ */
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { DEFAULT_HEADERS, HEADER_REQUEST_ID, HEADER_RESOLVED_VERSION, INFERIOR_API_VERSION, } from "./constants.js";
+import { AuthenticationError, DuplicateError, ForbiddenError, InferiorError, InsufficientScopeError, NotFoundError, PoisoningDetectedError, RateLimitError, ServerError, ValidationError, } from "./errors.js";
+import { DEFAULT_RETRY, withRetry } from "./retry.js";
+import { previewWorthiness } from "./_worthiness.js";
+import { SCHEMA_VERSION } from "./models.js";
+const DEFAULT_BASE_URL = "https://api.inferior.ai";
+const DEFAULT_TIMEOUT = 15_000; // ms
+function detectHostOs() {
+    const map = { darwin: "macos", linux: "linux", win32: "windows" };
+    return map[process.platform] ?? process.platform;
+}
+async function raiseForStatus(resp) {
+    if (resp.ok)
+        return;
+    const status = resp.status;
+    const requestId = resp.headers.get(HEADER_REQUEST_ID) ?? undefined;
+    let body = {};
+    try {
+        body = (await resp.json());
+    }
+    catch {
+        /* empty */
+    }
+    const errorType = body.error ?? "";
+    const message = body.message ?? resp.statusText;
+    const details = body.details ?? {};
+    if (status === 401)
+        throw new AuthenticationError(message, status, errorType, details, requestId);
+    if (status === 403) {
+        if (errorType === "InsufficientScopeError")
+            throw new InsufficientScopeError(message, status, errorType, details, requestId);
+        throw new ForbiddenError(message, status, errorType, details, requestId);
+    }
+    if (status === 404)
+        throw new NotFoundError(message, status, errorType, details, requestId);
+    if (status === 409)
+        throw new DuplicateError(message, status, errorType, details, requestId);
+    if (status === 422) {
+        // Phase C: distinguish poisoning-scanner rejections from PII/quality
+        // so callers can catch PoisoningDetectedError specifically.
+        const reason = details.rejection_reason ?? "";
+        const gate = details.gate ?? "";
+        const isPoisoning = errorType.toLowerCase().includes("poisoning") ||
+            reason === "poisoning_detected" ||
+            gate === "poisoning";
+        if (isPoisoning) {
+            throw new PoisoningDetectedError(message, status, errorType, details, requestId);
+        }
+        throw new ValidationError(message, status, errorType, details, requestId);
+    }
+    if (status === 429)
+        throw new RateLimitError(message, status, errorType, details, requestId);
+    if (status >= 500)
+        throw new ServerError(message, status, errorType, details, requestId);
+    throw new InferiorError(message, status, errorType, details, requestId);
+}
+export class InferiorClient {
+    apiKey;
+    baseUrl;
+    timeout;
+    hostOs;
+    baseModel;
+    framework;
+    retry;
+    fetcher;
+    /**
+     * Track whether we've warned about schema-version mismatch already.
+     * Kept instance-local so callers using multiple clients each warn once.
+     */
+    schemaMismatchWarned = false;
+    /**
+     * Same once-per-client pattern for the request-side API version
+     * handshake (Phase C2). Compares the backend's resolved version
+     * (header `X-Inferior-Resolved-Version`) to the SDK's compiled
+     * `INFERIOR_API_VERSION`; warns to console.warn once on mismatch.
+     */
+    apiVersionMismatchWarned = false;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        this.hostOs = detectHostOs();
+        this.baseModel = options.baseModel;
+        this.framework = options.framework;
+        this.retry = options.retry === false ? undefined : { ...DEFAULT_RETRY, ...(options.retry ?? {}) };
+        this.fetcher = options.fetch ?? fetch;
+    }
+    /**
+     * Phase G: emit a console.warn when response.schema_version's major
+     * component differs from ``SCHEMA_VERSION``. Missing schema_version is
+     * treated as "unknown" and silently ignored. Only warns once per client.
+     */
+    checkSchemaVersion(data) {
+        if (this.schemaMismatchWarned)
+            return;
+        const backendVersion = data?.schema_version;
+        if (typeof backendVersion !== "string" || !backendVersion)
+            return;
+        const backendMajor = Number.parseInt(backendVersion.split(".", 1)[0] ?? "", 10);
+        const sdkMajor = Number.parseInt(SCHEMA_VERSION.split(".", 1)[0] ?? "", 10);
+        if (Number.isNaN(backendMajor) || Number.isNaN(sdkMajor))
+            return;
+        if (backendMajor !== sdkMajor) {
+            this.schemaMismatchWarned = true;
+            // eslint-disable-next-line no-console
+            console.warn(`[inferior-sdk] Backend schema_version=${JSON.stringify(backendVersion)} ` +
+                `differs from SDK SCHEMA_VERSION=${JSON.stringify(SCHEMA_VERSION)}. ` +
+                `Upgrade the SDK to match the backend major version.`);
+        }
+    }
+    async request(method, path, options) {
+        let url = `${this.baseUrl}${path}`;
+        if (options?.params) {
+            const qs = new URLSearchParams(options.params).toString();
+            url += `?${qs}`;
+        }
+        const headers = {
+            ...DEFAULT_HEADERS,
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            ...(options?.headers ?? {}),
+        };
+        const doFetch = async () => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeout);
+            try {
+                return await this.fetcher(url, {
+                    method,
+                    headers,
+                    body: options?.body ? JSON.stringify(options.body) : undefined,
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        const resp = !this.retry ? await doFetch() : await withRetry(this.retry, method, headers, doFetch);
+        this.checkApiVersion(resp);
+        return resp;
+    }
+    /**
+     * Phase C2: warn once per client when backend's resolved API version
+     * differs from the SDK's compiled `INFERIOR_API_VERSION`. Cheap; no
+     * body access. Backend B2 ships the `X-Inferior-Resolved-Version`
+     * header on every response.
+     */
+    checkApiVersion(resp) {
+        if (this.apiVersionMismatchWarned)
+            return;
+        const resolved = resp.headers.get(HEADER_RESOLVED_VERSION);
+        if (!resolved || resolved === INFERIOR_API_VERSION)
+            return;
+        this.apiVersionMismatchWarned = true;
+        // eslint-disable-next-line no-console
+        console.warn(`[inferior-sdk] Backend resolved API version=${JSON.stringify(resolved)} ` +
+            `differs from SDK INFERIOR_API_VERSION=${JSON.stringify(INFERIOR_API_VERSION)}. ` +
+            `Backend likely supports your version transparently; if you see ` +
+            `incorrect responses, upgrade the SDK.`);
+    }
+    async json(method, path, options) {
+        const resp = await this.request(method, path, options);
+        await raiseForStatus(resp);
+        return (await resp.json());
+    }
+    // ── Search ──────────────────────────────────────────────────────────
+    async search(query, options) {
+        // Auto-populate conditions with detected environment
+        const mergedConditions = { ...(options?.conditions ?? {}) };
+        if (this.hostOs && !mergedConditions.host_os)
+            mergedConditions.host_os = this.hostOs;
+        if (this.baseModel && !mergedConditions.base_model)
+            mergedConditions.base_model = this.baseModel;
+        if (this.framework && !mergedConditions.framework)
+            mergedConditions.framework = this.framework;
+        const params = {
+            q: query,
+            limit: String(options?.limit ?? 5),
+            scope: options?.scope ?? "collective",
+        };
+        if (Object.keys(mergedConditions).length > 0)
+            params.conditions = JSON.stringify(mergedConditions);
+        if (options?.tags)
+            params.tags = options.tags.join(",");
+        if (options?.compact)
+            params.compact = "true";
+        if (options?.error_message)
+            params.error_message = options.error_message;
+        if (options?.your_conditions)
+            params.your_conditions = JSON.stringify(options.your_conditions);
+        // Phase E filter params — camelCase at the SDK boundary, snake_case on the wire.
+        if (options?.minCausalDepth != null)
+            params.min_causal_depth = String(options.minCausalDepth);
+        if (options?.minBoundaryPrecision != null)
+            params.min_boundary_precision = String(options.minBoundaryPrecision);
+        if (options?.minInsightTransferability != null)
+            params.min_insight_transferability = String(options.minInsightTransferability);
+        if (options?.evidenceClass)
+            params.evidence_class = options.evidenceClass;
+        if (options?.includeDrafts)
+            params.include_drafts = "true";
+        const data = await this.json("GET", "/v1/experiences/search", { params });
+        this.checkSchemaVersion(data);
+        const metadata = data.metadata ?? { cached: false };
+        const schemaVersion = data.schema_version ?? undefined;
+        if (options?.compact) {
+            return {
+                results: (data.results ?? []).map((r) => ({
+                    id: r.id ?? "",
+                    title: r.title ?? "",
+                    compact_summary: r.compact_summary,
+                    tags: r.tags ?? [],
+                    transfer_warnings: (r.transfer_warnings ?? []).map((tw) => tw.message),
+                })),
+                total_results: data.total_results ?? 0,
+                metadata,
+                schema_version: schemaVersion,
+            };
+        }
+        return {
+            results: data.results ?? [],
+            total_results: data.total_results ?? 0,
+            metadata,
+            schema_version: schemaVersion,
+        };
+    }
+    // ── Deposit ─────────────────────────────────────────────────────────
+    async deposit(input) {
+        const successful_approach = { method: input.solution };
+        if (input.implementation)
+            successful_approach.implementation = input.implementation;
+        if (input.time_to_resolution_minutes != null)
+            successful_approach.time_to_resolution_minutes = input.time_to_resolution_minutes;
+        const outcome = { status: input.outcome_status ?? "resolved" };
+        if (input.outcome_evidence)
+            outcome.evidence = input.outcome_evidence;
+        if (input.outcome_side_effects)
+            outcome.side_effects = input.outcome_side_effects;
+        // Phase B
+        if (input.evidence_class)
+            outcome.evidence_class = input.evidence_class;
+        const payload = {
+            title: input.title,
+            problem: input.problem,
+            successful_approach,
+            outcome,
+            root_cause: input.root_cause,
+            insight: input.insight,
+            tags: input.tags,
+            failed_approaches: input.failed_approaches ?? [],
+            applies_when: input.applies_when ?? [],
+            does_not_apply_when: input.does_not_apply_when ?? [],
+            creation_mode: input.creation_mode ?? "structured",
+            modality: input.modality ?? "text",
+            // Phase A: default "public" when caller omits.
+            visibility_scope: input.visibility_scope ?? "public",
+        };
+        if (input.origin)
+            payload.origin = input.origin;
+        // Auto-populate context.environment with detected host_os and framework.
+        // Phase B: merge env_versions into context.environment.versions.
+        const mergedContext = { ...(input.context ?? {}) };
+        const env = { ...(mergedContext.environment ?? {}) };
+        if (this.hostOs && !env.host_os)
+            env.host_os = this.hostOs;
+        if (this.framework && !env.framework)
+            env.framework = this.framework;
+        if (input.env_versions) {
+            const existingVersions = env.versions ?? {};
+            env.versions = { ...existingVersions, ...input.env_versions };
+        }
+        if (Object.keys(env).length > 0)
+            mergedContext.environment = env;
+        if (Object.keys(mergedContext).length > 0)
+            payload.context = mergedContext;
+        const headers = input.idempotencyKey ? { "Idempotency-Key": input.idempotencyKey } : undefined;
+        const resp = await this.json("POST", "/v1/experiences", { body: payload, headers });
+        this.checkSchemaVersion(resp);
+        return resp;
+    }
+    async depositRaw(input) {
+        if (!input.content && !input.problem) {
+            throw new Error("Either 'content' or 'problem' must be provided.");
+        }
+        const payload = { creation_mode: input.creation_mode ?? "raw" };
+        if (input.content)
+            payload.content = input.content;
+        if (input.problem)
+            payload.problem = input.problem;
+        if (input.what_worked)
+            payload.what_worked = input.what_worked;
+        if (input.context)
+            payload.context = input.context;
+        if (input.what_was_tried)
+            payload.what_was_tried = input.what_was_tried;
+        if (input.outcome)
+            payload.outcome = input.outcome;
+        if (input.root_cause)
+            payload.root_cause = input.root_cause;
+        if (input.insight)
+            payload.insight = input.insight;
+        if (input.tags)
+            payload.tags = input.tags;
+        const headers = input.idempotencyKey ? { "Idempotency-Key": input.idempotencyKey } : undefined;
+        return this.json("POST", "/v1/experiences/raw", { body: payload, headers });
+    }
+    async depositFile(path, options) {
+        const content = await readFile(path, "utf-8");
+        const fileName = basename(path);
+        const formData = new FormData();
+        formData.append("file", new Blob([content], { type: "text/plain" }), fileName);
+        if (options?.tags)
+            formData.append("tags", JSON.stringify(options.tags));
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const resp = await this.fetcher(`${this.baseUrl}/v1/experiences/raw/file`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+                body: formData,
+                signal: controller.signal,
+            });
+            await raiseForStatus(resp);
+            return (await resp.json());
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // ── Feedback ────────────────────────────────────────────────────────
+    async feedback(experienceId, input) {
+        const payload = { was_helpful: input.was_helpful };
+        if (input.helpfulness_detail)
+            payload.helpfulness_detail = input.helpfulness_detail;
+        if (input.context_note)
+            payload.context_note = input.context_note;
+        if (input.time_saved_minutes != null)
+            payload.time_saved_minutes = input.time_saved_minutes;
+        if (input.your_conditions)
+            payload.your_conditions = input.your_conditions;
+        return this.json("POST", `/v1/experiences/${experienceId}/feedback`, { body: payload });
+    }
+    // ── Experience ──────────────────────────────────────────────────────
+    async getExperience(id) {
+        return this.json("GET", `/v1/experiences/${id}`);
+    }
+    async retractExperience(id, reason) {
+        const body = reason ? { reason } : {};
+        return this.json("POST", `/v1/experiences/${id}/retract`, { body });
+    }
+    // ── Agent Registration ──────────────────────────────────────────────
+    static async register(options = {}) {
+        const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        const payload = {
+            type: options.agentType ?? "ai_agent",
+            host_os: detectHostOs(),
+        };
+        if (options.inviteCode)
+            payload.invite_code = options.inviteCode;
+        if (options.name)
+            payload.agent_name = options.name;
+        if (options.platform)
+            payload.platform = options.platform;
+        if (options.baseModel)
+            payload.base_model = options.baseModel;
+        if (options.framework)
+            payload.framework = options.framework;
+        const resp = await fetch(`${baseUrl}/v1/agents/register`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+        await raiseForStatus(resp);
+        return (await resp.json());
+    }
+    // ── Agent Info & Keys ───────────────────────────────────────────────
+    async getMe() {
+        return this.json("GET", "/v1/agents/me");
+    }
+    async getKeys(contributorId) {
+        return this.json("GET", `/v1/agents/${contributorId}/keys`);
+    }
+    async createKey(contributorId, input) {
+        const body = {
+            name: input.name,
+            scope: input.scope ?? "full",
+            expires_at: input.expires_at ?? null,
+        };
+        // Phase A: optional workspace scope for team-visibility access.
+        if (input.workspace_id != null)
+            body.workspace_id = input.workspace_id;
+        return this.json("POST", `/v1/agents/${contributorId}/keys`, { body });
+    }
+    async revokeKey(contributorId, keyId) {
+        const resp = await this.request("DELETE", `/v1/agents/${contributorId}/keys/${keyId}`);
+        await raiseForStatus(resp);
+    }
+    // ── Profile & Stats ─────────────────────────────────────────────────
+    async getProfile() {
+        return this.json("GET", "/v1/agents/me/profile");
+    }
+    async contextCheck(input) {
+        const payload = { task_description: input.task_description };
+        if (input.tools)
+            payload.tools = input.tools;
+        if (input.environment)
+            payload.environment = input.environment;
+        return this.json("POST", "/v1/experiences/context-check", { body: payload });
+    }
+    async getStats() {
+        return this.json("GET", "/v1/stats");
+    }
+    async batchSearch(queries) {
+        return this.json("POST", "/v1/experiences/search/batch", { body: { queries } });
+    }
+    /**
+     * Phase E: retrieve agent-demand hotspots — queries where agents
+     * searched but found no high-quality results.
+     *
+     * Requires an API key with **full** scope (admin-only endpoint).
+     *
+     * @throws {InsufficientScopeError} Key lacks ``full`` scope.
+     */
+    async demandHotspots(options) {
+        const params = {
+            days: String(options?.days ?? 7),
+            max_top_score: String(options?.maxTopScore ?? 0.3),
+            limit: String(options?.limit ?? 50),
+        };
+        if (options?.domain)
+            params.domain = options.domain;
+        return this.json("GET", "/v1/demand/hotspots", { params });
+    }
+    // ── Local Decision Helpers (v1.0+) ──────────────────────────────────
+    //
+    // Pure functions supporting the framework's local-first model. No
+    // network, no I/O. Exposed as static methods so callers can use them
+    // either on an instance or on the class itself.
+    /** v1.2+: mid-session search limit. Set to 0 to disable the budget gate. */
+    static MID_SESSION_SEARCH_LIMIT = 2;
+    /** v1.2+: correction-language regex patterns used by the signal detectors. */
+    static CORRECTION_LANGUAGE_PATTERNS = [
+        "\\bno\\b",
+        "\\bactually\\b",
+        "\\binstead of\\b",
+        "\\bredo\\b",
+        "\\bfix\\b",
+        "\\bimprove\\b",
+        "\\bwrong\\b",
+        "not what I (meant|want)",
+        "the tone is",
+        "too (formal|casual|long|short|terse|verbose)",
+        "\\breword\\b",
+        "\\bshorten\\b",
+        "\\bexpand\\b",
+        "add more detail",
+        "remove the",
+        "try again",
+        "let'?s also",
+        "\\bmissing\\b",
+        "\\bforgot\\b",
+    ];
+    /**
+     * Local gate: decide whether to call ``search``. Pure function.
+     *
+     * Anti-triggers override triggers — if any anti-trigger fires, return
+     * false regardless of triggers. Otherwise any trigger returns true.
+     * No triggers → false (framework bias: when in doubt, skip).
+     *
+     * v1.2+ additions:
+     * - If ``trace`` is provided, auto-derive ``isErrorShaped``,
+     *   ``hasRejectedOutputThisSession``, and ``userMessageHasWarning``
+     *   from the trace.
+     * - Enforces mid-session search budget: when
+     *   ``signals.searchesThisSession >= MID_SESSION_SEARCH_LIMIT`` and
+     *   the limit > 0, returns false with a ``console.warn``.
+     */
+    static shouldSearch(signals, trace) {
+        let isErrorShaped = signals.isErrorShaped;
+        let hasRejectedOutput = signals.hasRejectedOutputThisSession;
+        let userWarning = signals.userMessageHasWarning;
+        if (trace) {
+            if ((trace.toolCalls ?? []).some((tc) => tc.outcome === "error")) {
+                isErrorShaped = true;
+            }
+            if ((trace.outputs ?? []).some((o) => o.accepted === false)) {
+                hasRejectedOutput = true;
+            }
+            const patterns = InferiorClient.CORRECTION_LANGUAGE_PATTERNS.map((p) => new RegExp(p, "i"));
+            if ((trace.userMessages ?? []).some((um) => um.index > 0 && patterns.some((p) => p.test(um.content)))) {
+                userWarning = true;
+            }
+        }
+        const limit = InferiorClient.MID_SESSION_SEARCH_LIMIT;
+        if (limit > 0 && (signals.searchesThisSession ?? 0) >= limit) {
+            // eslint-disable-next-line no-console
+            console.warn(`[inferior-sdk] Mid-session search budget exhausted ` +
+                `(searchesThisSession=${signals.searchesThisSession ?? 0} >= ` +
+                `MID_SESSION_SEARCH_LIMIT=${limit}). Skipping. ` +
+                `Set InferiorClient.MID_SESSION_SEARCH_LIMIT = 0 to disable.`);
+            return false;
+        }
+        if (signals.isTrivial ||
+            signals.isCreative ||
+            signals.repeatWithinSession ||
+            signals.isNearZeroCoverage ||
+            signals.isProprietaryClosed ||
+            signals.isLatencySensitive ||
+            signals.isMidFragment) {
+            return false;
+        }
+        if (isErrorShaped)
+            return true;
+        if (signals.isHighStakes)
+            return true;
+        if (signals.isUnfamiliar)
+            return true;
+        if (signals.isLongCommitment)
+            return true;
+        if (signals.isRegulatory)
+            return true;
+        // v1.2 additions.
+        if (hasRejectedOutput)
+            return true;
+        if (signals.isRepeatedPattern)
+            return true;
+        if (userWarning)
+            return true;
+        // Stuck signal: must have BOTH a failed attempt AND elapsed time.
+        if ((signals.failedAttempts ?? 0) >= 1 && (signals.elapsedMinutes ?? 0) >= 5) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Derive worthiness signals from an execution trace (v1.2+).
+     * Framework Phase 1 for deposits, domain-agnostic.
+     */
+    static detectDepositSignals(trace) {
+        const signals = [];
+        const toolCalls = trace.toolCalls ?? [];
+        const outputs = trace.outputs ?? [];
+        const userMessages = trace.userMessages ?? [];
+        const searches = trace.searchesPerformed ?? [];
+        const hasToolError = toolCalls.some((tc) => tc.outcome === "error");
+        const hasOutputRejection = outputs.some((o) => o.accepted === false);
+        const hasExplicitAccept = outputs.some((o) => o.accepted === true);
+        const sessionSucceeded = (trace.outcome ?? "success") === "success";
+        // Signal 1: error_recovery (broadened).
+        if ((hasToolError || hasOutputRejection) && sessionSucceeded) {
+            signals.push({
+                type: "error_recovery",
+                count: toolCalls.filter((tc) => tc.outcome === "error").length +
+                    outputs.filter((o) => o.accepted === false).length,
+                evidence: "attempt rejected → subsequent success",
+            });
+        }
+        // NEW: output_rejection_recovery.
+        if (hasOutputRejection && hasExplicitAccept) {
+            signals.push({
+                type: "output_rejection_recovery",
+                count: outputs.filter((o) => o.accepted === false).length,
+                evidence: "explicit accepted=false → accepted=true pair",
+            });
+        }
+        // Signal 2: high_retry.
+        const goalCounts = {};
+        for (const tc of toolCalls) {
+            const key = tc.goal ?? tc.name;
+            if (key)
+                goalCounts[key] = (goalCounts[key] ?? 0) + 1;
+        }
+        const maxToolRetry = Object.values(goalCounts).reduce((a, b) => Math.max(a, b), 0);
+        const outputRetryCount = outputs.length;
+        if (maxToolRetry >= 3 || outputRetryCount >= 3) {
+            const count = Math.max(maxToolRetry, outputRetryCount);
+            signals.push({
+                type: "high_retry",
+                count,
+                evidence: `goal/output retried ${count} times`,
+            });
+        }
+        // Signal 3: plan_deviation.
+        const successfulTools = toolCalls.filter((tc) => tc.outcome === "success");
+        if (successfulTools.length >= 2 && toolCalls.length > 0) {
+            const first = toolCalls[0].name;
+            const last = successfulTools[successfulTools.length - 1].name;
+            if (first && last && first !== last) {
+                signals.push({
+                    type: "plan_deviation",
+                    count: 1,
+                    evidence: `first tool '${first}' → final successful '${last}'`,
+                });
+            }
+        }
+        // Signal 4: human_correction.
+        const patterns = InferiorClient.CORRECTION_LANGUAGE_PATTERNS.map((p) => new RegExp(p, "i"));
+        const correctionSamples = [];
+        for (const um of userMessages) {
+            if (um.index > 0 && patterns.some((p) => p.test(um.content))) {
+                correctionSamples.push(um.content.slice(0, 80));
+            }
+        }
+        for (const o of outputs) {
+            if (o.userFeedback && patterns.some((p) => p.test(o.userFeedback))) {
+                correctionSamples.push(o.userFeedback.slice(0, 80));
+            }
+        }
+        if (correctionSamples.length > 0) {
+            signals.push({
+                type: "human_correction",
+                count: correctionSamples.length,
+                evidence: `${correctionSamples.length} correction-language match(es)`,
+                metadata: { samples: correctionSamples.slice(0, 3) },
+            });
+        }
+        // Signal 5: search_miss.
+        const misses = searches.filter((s) => s.resultCount === 0 || s.topScore < 0.3);
+        if (misses.length > 0 && sessionSucceeded) {
+            signals.push({
+                type: "search_miss",
+                count: misses.length,
+                evidence: `${misses.length} unmet search(es) preceded success`,
+                metadata: { queries: misses.slice(0, 3).map((m) => m.query) },
+            });
+        }
+        return signals;
+    }
+    /** v1.2+: search-side signal detection from an execution trace. */
+    static detectSearchSignals(trace) {
+        const signals = [];
+        const toolCalls = trace.toolCalls ?? [];
+        const outputs = trace.outputs ?? [];
+        const userMessages = trace.userMessages ?? [];
+        const errors = toolCalls.filter((tc) => tc.outcome === "error");
+        if (errors.length > 0) {
+            signals.push({
+                type: "error_state",
+                count: errors.length,
+                evidence: `${errors.length} tool-call error(s) in trace`,
+            });
+        }
+        const rejections = outputs.filter((o) => o.accepted === false);
+        if (rejections.length > 0) {
+            signals.push({
+                type: "output_rejection_state",
+                count: rejections.length,
+                evidence: `${rejections.length} output(s) rejected by user`,
+            });
+        }
+        const patterns = InferiorClient.CORRECTION_LANGUAGE_PATTERNS.map((p) => new RegExp(p, "i"));
+        for (const um of userMessages) {
+            if (um.index > 0 && patterns.some((p) => p.test(um.content))) {
+                signals.push({
+                    type: "user_warning",
+                    count: 1,
+                    evidence: "mid-task user message with correction language",
+                });
+                break;
+            }
+        }
+        return signals;
+    }
+    /**
+     * Build a search-worthy query from a draft and context (v1.2+).
+     * Framework Phase 2 for search.
+     */
+    static formSearchQuery(draftQuery, context) {
+        const ctx = context ?? {};
+        const pieces = draftQuery.trim() ? [draftQuery.trim()] : [];
+        const added = [];
+        const lower = (draftQuery ?? "").toLowerCase();
+        for (const tech of ctx.techStack ?? []) {
+            if (!lower.includes(tech.toLowerCase()))
+                added.push(tech);
+        }
+        for (const [name, version] of Object.entries(ctx.versions ?? {})) {
+            const token = `${name} ${version}`;
+            if (!lower.includes(token.toLowerCase()))
+                added.push(token);
+        }
+        for (const [key, val] of Object.entries(ctx.environment ?? {})) {
+            const token = key ? `${key}=${val}` : val;
+            if (!lower.includes(token.toLowerCase()))
+                added.push(token);
+        }
+        for (const c of ctx.constraints ?? []) {
+            if (!lower.includes(c.toLowerCase()))
+                added.push(c);
+        }
+        if (ctx.errorMessage) {
+            const safety = InferiorClient.isQuerySafe(ctx.errorMessage);
+            if (safety.isSafe) {
+                added.push(ctx.errorMessage.slice(0, 120));
+            }
+            // else: silently skip unsafe error message.
+        }
+        const formed = [...pieces, ...added].join(" ").trim();
+        const wordCount = formed ? formed.split(/\s+/).length : 0;
+        const reasons = [];
+        let isUsable = true;
+        if (wordCount < 3) {
+            isUsable = false;
+            reasons.push(`Query too vague (${wordCount} word(s); need ≥3).`);
+        }
+        const finalSafety = InferiorClient.isQuerySafe(formed);
+        if (!finalSafety.isSafe) {
+            isUsable = false;
+            for (const r of finalSafety.reasons)
+                reasons.push(`Unsafe: ${r}`);
+        }
+        return {
+            formedQuery: formed,
+            isUsable,
+            wordCount,
+            reasons,
+            droppedProjectTerms: [],
+        };
+    }
+    /**
+     * Local gate: score a deposit draft before sending. Pure function.
+     *
+     * Checks four locally-evaluable hard dimensions (causal depth,
+     * boundary precision, evidence honesty, non-triviality) AND (v1.2+)
+     * produces a 5-dimension preview of the server's worthiness scoring
+     * (novelty, transferability, consequence, evidence, recurrence).
+     *
+     * Does NOT make any network calls. Caller should still search
+     * Inferior before depositing to confirm the novelty dimension.
+     */
+    static depositWorthiness(draft, signalsFired) {
+        const reasons = [];
+        const failed = [];
+        const addFailed = (dim) => {
+            if (!failed.includes(dim))
+                failed.push(dim);
+        };
+        const nonTrivialChecks = [
+            [draft.isTrivialFix, "Task is a trivial fix (rename/format/typo); skip."],
+            [draft.isDocumentationOnly, "Following documentation verbatim; skip."],
+            [
+                draft.isWellKnownPattern,
+                "Well-known pattern already in Stack Overflow / official docs / training data; skip.",
+            ],
+            [draft.isTrialAndErrorGuess, "Trial-and-error fix you don't understand; skip."],
+            [
+                draft.isContextSpecificOnly,
+                "Solution is context-specific to this codebase; skip or use visibility_scope='private'.",
+            ],
+        ];
+        for (const [flag, reason] of nonTrivialChecks) {
+            if (flag) {
+                addFailed("non_trivial");
+                reasons.push(reason);
+            }
+        }
+        const rc = (draft.root_cause ?? "").trim();
+        if (rc.length < 30) {
+            addFailed("causal_depth");
+            reasons.push("root_cause is too short (<30 chars). Explain WHY the problem occurred, not just what happened.");
+        }
+        else if (draft.problem && rc.toLowerCase() === draft.problem.trim().toLowerCase()) {
+            addFailed("causal_depth");
+            reasons.push("root_cause just restates the problem. Explain the causal mechanism.");
+        }
+        if (!draft.does_not_apply_when || draft.does_not_apply_when.length === 0) {
+            addFailed("boundary_precision");
+            reasons.push("does_not_apply_when is empty. State at least one condition where the solution does NOT apply — if you can't name one, you don't yet understand the boundary.");
+        }
+        if (draft.evidence_class == null || draft.evidence_class === undefined) {
+            addFailed("evidence");
+            reasons.push("evidence_class is unset. Tag honestly: production_validated / integration_tested / local_tested / self_reported / speculative.");
+        }
+        else if (draft.hasBeenVerified === false &&
+            ["production_validated", "integration_tested", "local_tested"].includes(draft.evidence_class)) {
+            addFailed("evidence");
+            reasons.push(`evidence_class='${draft.evidence_class}' claims verification but hasBeenVerified=false. Downgrade to 'self_reported' or 'speculative'.`);
+        }
+        // Soft nudges.
+        if (!draft.failed_approaches || draft.failed_approaches.length === 0) {
+            reasons.push("(soft) No failed_approaches listed — failed attempts are often the most valuable part of a deposit.");
+        }
+        if (!(draft.insight ?? "").trim()) {
+            reasons.push("(soft) insight is empty — add the transferable lesson so other agents can apply it elsewhere.");
+        }
+        const hardDimensions = 4;
+        const failedCount = failed.length;
+        const score = Math.max(0, (hardDimensions - failedCount) / hardDimensions);
+        const shouldDeposit = failedCount === 0;
+        if (shouldDeposit) {
+            reasons.unshift("All four local dimensions (causal depth, boundary precision, evidence, non-triviality) pass. Still search Inferior before depositing to confirm novelty.");
+        }
+        // v1.2+: 5-dimension preview using shared math.
+        const preview = previewWorthiness(draft, signalsFired);
+        reasons.push(`--- Server worthiness preview ` +
+            `(estimated score: ${preview.estimatedServerScore.toFixed(2)}, ` +
+            `base: ${preview.baseScore.toFixed(2)}) ---`);
+        for (const dim of Object.keys(preview.dimensionScores)) {
+            const s = preview.dimensionScores[dim];
+            const conf = preview.dimensionConfidence[dim];
+            reasons.push(`  ${dim}: ${s.toFixed(2)} (${conf}) — ${preview.dimensionReasons[dim]}`);
+        }
+        for (const br of preview.boostReasons) {
+            reasons.push(`  boost: ${br}`);
+        }
+        return {
+            shouldDeposit,
+            score,
+            reasons,
+            failedDimensions: failed,
+            dimensionScores: preview.dimensionScores,
+            dimensionConfidence: preview.dimensionConfidence,
+            estimatedServerScore: preview.estimatedServerScore,
+            wouldLikelyAccept: preview.wouldLikelyAccept,
+        };
+    }
+    /**
+     * Local privacy gate: classify a query as safe to send. Pure function.
+     * Classifies, does not redact — caller decides whether to abort,
+     * rewrite, or proceed. Default policy is conservative.
+     */
+    static isQuerySafe(query, policy) {
+        const blockSecrets = policy?.blockSecrets ?? true;
+        const blockInternalHosts = policy?.blockInternalHosts ?? true;
+        const blockCustomerData = policy?.blockCustomerData ?? true;
+        const customDenyPatterns = policy?.customDenyPatterns ?? [];
+        const maxLength = policy?.maxLength ?? 2000;
+        const reasons = [];
+        if (query.length > maxLength) {
+            reasons.push(`Query length (${query.length}) exceeds maxLength (${maxLength}). Shorten to avoid accidentally dumping file contents.`);
+        }
+        if (blockSecrets) {
+            const secretPatterns = [
+                /(aws_access_key|aws_secret|sk_live_|sk_test_|ghp_|github_pat_)/i,
+                /-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----/,
+                /(api[_-]?key|bearer|token)["'\s:=]+[A-Za-z0-9_\-]{20,}/i,
+            ];
+            if (secretPatterns.some((pat) => pat.test(query))) {
+                reasons.push("Query appears to contain a secret (API key, token, or private key). Do not send.");
+            }
+        }
+        if (blockInternalHosts) {
+            const hostPatterns = [
+                /\b[\w-]+\.internal\b/,
+                /\b[\w-]+\.corp\b/,
+                /\b[\w-]+\.local\b/,
+                /\blocalhost:\d+\b/,
+                /\b10\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/,
+                /\b192\.168\.\d{1,3}\.\d{1,3}\b/,
+                /\b172\.(1[6-9]|2\d|3[0-1])\.\d{1,3}\.\d{1,3}\b/,
+            ];
+            if (hostPatterns.some((pat) => pat.test(query))) {
+                reasons.push("Query contains an internal hostname or private IP. Abstract it before sending.");
+            }
+        }
+        if (blockCustomerData) {
+            const dataPatterns = [
+                [/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/, "email address"],
+                [/\b\d{3}-\d{2}-\d{4}\b/, "SSN"],
+                [/\b(?:\d[ -]?){13,19}\b/, "credit card / long number sequence"],
+                [/\+?1?[-.\s]?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}/, "phone number"],
+            ];
+            for (const [pat, label] of dataPatterns) {
+                if (pat.test(query)) {
+                    reasons.push(`Query appears to contain a ${label}. Abstract it before sending.`);
+                }
+            }
+        }
+        for (const patStr of customDenyPatterns) {
+            try {
+                const pat = new RegExp(patStr);
+                if (pat.test(query)) {
+                    reasons.push(`Query matches custom deny pattern: ${patStr}`);
+                }
+            }
+            catch {
+                // Invalid regex — caller's problem; don't crash.
+            }
+        }
+        return { isSafe: reasons.length === 0, reasons };
+    }
+}
+//# sourceMappingURL=client.js.map