mewkit 1.14.0 → 1.15.0

package/dist/core/repo-context-adapter.d.ts

@@ -0,0 +1,23 @@
+/** A host-native tool the agent invokes to acquire evidence (MeowKit only names it). */
+export interface AcquisitionTool {
+    /** Host-native/logical tool identifier — e.g. "Read", "Grep+Glob", "shell:ripgrep". */
+    tool: string;
+    /** Plain-language note on what the tool does / any advisory caveat. */
+    note: string;
+}
+export interface AcquisitionDescriptor {
+    provider: string;
+    /** `supported` = typed host tools; `partial` = shell-mediated (advisory); `report-only` = none. */
+    status: "supported" | "partial" | "report-only";
+    /** How the host reads a file's content. null ⇒ no read surface (report-only). */
+    read: AcquisitionTool | null;
+    /** How the host searches for task-relevant paths/symbols. null ⇒ no search surface. */
+    search: AcquisitionTool | null;
+    /** Plain-language basis for the claim — what makes the status what it is. */
+    evidence: string;
+}
+/** Providers whose acquisition surface is authored + evidenced. Others are report-only. */
+export declare const ACQUISITION_DESCRIPTORS: Record<string, AcquisitionDescriptor>;
+/** The acquisition descriptor for a provider, or a report-only fallback that claims nothing. */
+export declare function getAcquisitionDescriptor(provider: string): AcquisitionDescriptor;
+//# sourceMappingURL=repo-context-adapter.d.ts.map

package/dist/core/repo-context-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-context-adapter.d.ts","sourceRoot":"","sources":["../../src/core/repo-context-adapter.ts"],"names":[],"mappings":"AAQA,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC/B,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,mGAAmG;IACnG,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,aAAa,CAAC;IAChD,iFAAiF;IACjF,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IAC7B,uFAAuF;IACvF,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,2FAA2F;AAC3F,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAwBzE,CAAC;AAEF,gGAAgG;AAChG,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAUhF"}

package/dist/core/repo-context-adapter.js

@@ -0,0 +1,44 @@
+// Per-provider repo-context ACQUISITION descriptors (Phase 5 slice 3). Given a provider, this
+// names the host-native read + search tools the AGENT uses to acquire task-scoped evidence.
+// MeowKit NEVER executes these tools — it is the outer harness: it selects the contract and
+// records the resulting envelope (`context record`), while the inner runtime does the reading.
+// This mirrors provider-projection.ts: a trusted constant that must not over-claim. A provider
+// with no tested acquisition surface is `report-only` with null read/search — no capability to
+// acquire is asserted, so the orchestrator falls back to host-provided paths only.
+/** Providers whose acquisition surface is authored + evidenced. Others are report-only. */
+export const ACQUISITION_DESCRIPTORS = {
+    "claude-code": {
+        provider: "claude-code",
+        status: "supported",
+        read: { tool: "Read", note: "typed host-native file read" },
+        search: { tool: "Grep+Glob", note: "typed content search (Grep) + filename search (Glob)" },
+        evidence: "Claude Code exposes typed Read/Grep/Glob tools the agent invokes to acquire evidence; MeowKit records the resulting envelope.",
+    },
+    "claude-plugin": {
+        provider: "claude-plugin",
+        status: "supported",
+        read: { tool: "Read", note: "typed host-native file read (same Claude Code host)" },
+        search: { tool: "Grep+Glob", note: "typed content + filename search (same Claude Code host)" },
+        evidence: "The plugin runs in the Claude Code host — identical typed Read/Grep/Glob acquisition surface.",
+    },
+    codex: {
+        provider: "codex",
+        status: "partial",
+        // Codex acquires through its shell, not a typed tool contract. Honest, not fabricated: we
+        // name the shell tools it actually uses (cat/ripgrep) and mark the whole surface advisory.
+        read: { tool: "shell:cat", note: "shell-mediated read — no typed read tool (advisory)" },
+        search: { tool: "shell:ripgrep", note: "shell-mediated search — no typed search tool (advisory)" },
+        evidence: "Codex acquires via its shell (cat/ripgrep), not a typed tool contract; acquisition works but is shell-mediated (advisory) ⇒ partial.",
+    },
+};
+/** The acquisition descriptor for a provider, or a report-only fallback that claims nothing. */
+export function getAcquisitionDescriptor(provider) {
+    return (ACQUISITION_DESCRIPTORS[provider] ?? {
+        provider,
+        status: "report-only",
+        read: null,
+        search: null,
+        evidence: "No tested acquisition surface for this provider — report-only; the orchestrator relies on host-provided paths only.",
+    });
+}
+//# sourceMappingURL=repo-context-adapter.js.map

package/dist/core/repo-context-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-context-adapter.js","sourceRoot":"","sources":["../../src/core/repo-context-adapter.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,4FAA4F;AAC5F,4FAA4F;AAC5F,+FAA+F;AAC/F,+FAA+F;AAC/F,+FAA+F;AAC/F,mFAAmF;AAsBnF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,uBAAuB,GAA0C;IAC7E,aAAa,EAAE;QACd,QAAQ,EAAE,aAAa;QACvB,MAAM,EAAE,WAAW;QACnB,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,6BAA6B,EAAE;QAC3D,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,sDAAsD,EAAE;QAC3F,QAAQ,EAAE,+HAA+H;KACzI;IACD,eAAe,EAAE;QAChB,QAAQ,EAAE,eAAe;QACzB,MAAM,EAAE,WAAW;QACnB,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,qDAAqD,EAAE;QACnF,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,yDAAyD,EAAE;QAC9F,QAAQ,EAAE,+FAA+F;KACzG;IACD,KAAK,EAAE;QACN,QAAQ,EAAE,OAAO;QACjB,MAAM,EAAE,SAAS;QACjB,0FAA0F;QAC1F,2FAA2F;QAC3F,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,qDAAqD,EAAE;QACxF,MAAM,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,yDAAyD,EAAE;QAClG,QAAQ,EAAE,sIAAsI;KAChJ;CACD,CAAC;AAEF,gGAAgG;AAChG,MAAM,UAAU,wBAAwB,CAAC,QAAgB;IACxD,OAAO,CACN,uBAAuB,CAAC,QAAQ,CAAC,IAAI;QACpC,QAAQ;QACR,MAAM,EAAE,aAAa;QACrB,IAAI,EAAE,IAAI;QACV,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,qHAAqH;KAC/H,CACD,CAAC;AACH,CAAC"}

package/dist/core/repo-context.d.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+/**
+ * A path is secret-shaped when ANY of its segments looks like a credential/key store
+ * (mirrors + extends injection-rules Rule 4). Checked per-segment so a `secrets/` or
+ * `.ssh/` directory anywhere in the path is caught, not just the basename.
+ */
+export declare function isSecretPath(p: string): boolean;
+export interface OwningRepo {
+    /** Repo root (git) or the boundary root (non-git) — a stable identity, never invented. */
+    identity: string;
+    /** Git HEAD revision when resolvable; null for non-git or unresolvable HEAD (provenance only). */
+    revision: string | null;
+    isGit: boolean;
+}
+/**
+ * Resolve the repository that OWNS `absPath` by walking up to the nearest ancestor containing
+ * a `.git` marker (never crossing above `boundaryRoot` when given). A git match yields the repo
+ * root + its HEAD revision; no match yields the boundary root (or the path's dir) as a stable
+ * non-git identity with a null revision — never a fabricated one. Each path resolves to its OWN
+ * nested repo, so a multi-repo parent (e.g. Aspire) is not treated as one repository.
+ */
+export declare function resolveOwningRepo(absPath: string, boundaryRoot?: string): OwningRepo;
+export declare const EvidenceRefSchema: z.ZodObject<{
+    path: z.ZodString;
+    /** SHA-256 of the file content at record time, or null when the file was missing. */
+    contentHash: z.ZodNullable<z.ZodString>;
+    owningRepoIdentity: z.ZodString;
+    revision: z.ZodNullable<z.ZodString>;
+    provenance: z.ZodDefault<z.ZodEnum<["host-read", "host-search"]>>;
+    /** True when the path is secret-shaped and its content must not be persisted verbatim. */
+    redacted: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    provenance: "host-read" | "host-search";
+    contentHash: string | null;
+    owningRepoIdentity: string;
+    revision: string | null;
+    redacted: boolean;
+}, {
+    path: string;
+    contentHash: string | null;
+    owningRepoIdentity: string;
+    revision: string | null;
+    provenance?: "host-read" | "host-search" | undefined;
+    redacted?: boolean | undefined;
+}>;
+export type EvidenceRef = z.infer<typeof EvidenceRefSchema>;
+export declare const ContextEnvelopeSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1.0">;
+    /** The task's scope/container (e.g. an Aspire-style parent holding many repos). It is NOT
+     * itself a repository — each evidence ref names its OWN owning repo + revision. Multi-repo
+     * context is therefore never collapsed into one identity. */
+    boundaryRoot: z.ZodString;
+    evidence: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        /** SHA-256 of the file content at record time, or null when the file was missing. */
+        contentHash: z.ZodNullable<z.ZodString>;
+        owningRepoIdentity: z.ZodString;
+        revision: z.ZodNullable<z.ZodString>;
+        provenance: z.ZodDefault<z.ZodEnum<["host-read", "host-search"]>>;
+        /** True when the path is secret-shaped and its content must not be persisted verbatim. */
+        redacted: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        provenance: "host-read" | "host-search";
+        contentHash: string | null;
+        owningRepoIdentity: string;
+        revision: string | null;
+        redacted: boolean;
+    }, {
+        path: string;
+        contentHash: string | null;
+        owningRepoIdentity: string;
+        revision: string | null;
+        provenance?: "host-read" | "host-search" | undefined;
+        redacted?: boolean | undefined;
+    }>, "many">>;
+    queryDescriptor: z.ZodDefault<z.ZodString>;
+    toolDescriptor: z.ZodDefault<z.ZodString>;
+    timestamp: z.ZodString;
+    omissions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: "1.0";
+    boundaryRoot: string;
+    evidence: {
+        path: string;
+        provenance: "host-read" | "host-search";
+        contentHash: string | null;
+        owningRepoIdentity: string;
+        revision: string | null;
+        redacted: boolean;
+    }[];
+    queryDescriptor: string;
+    toolDescriptor: string;
+    timestamp: string;
+    omissions: string[];
+}, {
+    schemaVersion: "1.0";
+    boundaryRoot: string;
+    timestamp: string;
+    evidence?: {
+        path: string;
+        contentHash: string | null;
+        owningRepoIdentity: string;
+        revision: string | null;
+        provenance?: "host-read" | "host-search" | undefined;
+        redacted?: boolean | undefined;
+    }[] | undefined;
+    queryDescriptor?: string | undefined;
+    toolDescriptor?: string | undefined;
+    omissions?: string[] | undefined;
+}>;
+export type ContextEnvelope = z.infer<typeof ContextEnvelopeSchema>;
+export interface RepoRef {
+    identity: string;
+    revision: string | null;
+}
+/**
+ * The DISTINCT owning repositories represented in an evidence set, each with its own revision.
+ * This is the multi-repo context view: a task touching several repos under one container (e.g.
+ * Aspire) surfaces every repo separately — no repo's identity/revision is lost or conflated.
+ */
+export declare function distinctRepos(refs: EvidenceRef[]): RepoRef[];
+/** Hash an evidence file for freshness; null when it does not exist (missing evidence). */
+export declare function hashEvidence(absPath: string): string | null;
+/**
+ * Build an evidence reference for a path: owning repo + revision, content hash, and a redaction
+ * flag for secret-shaped paths (whose CONTENT must never be persisted — only the hash + flag).
+ */
+export declare function buildEvidenceRef(absPath: string, boundaryRoot: string, provenance?: EvidenceRef["provenance"]): EvidenceRef;
+export type FreshnessStatus = "fresh" | "stale" | "missing" | "out-of-scope";
+/**
+ * Path-scoped freshness: re-hash each recorded evidence path and compare to its recorded hash.
+ * A repo advancing its revision does NOT make untouched files stale — only a changed hash does.
+ *
+ * SECURITY: an envelope is untrusted DATA (it can ship in a third-party repo or be produced by
+ * an injection-tricked agent). When `boundaryRoot` is given, a path outside it is reported
+ * `out-of-scope` and is NEVER stat-ed or hashed — otherwise `check` would become an
+ * existence/hash oracle for arbitrary absolute paths (e.g. `~/.ssh/id_rsa`, `/etc/passwd`).
+ */
+export declare function checkEvidenceFreshness(refs: EvidenceRef[], boundaryRoot?: string): {
+    path: string;
+    status: FreshnessStatus;
+}[];
+/** True when `target` stays within `boundaryRoot` (lexical; used to reject out-of-scope evidence). */
+export declare function isWithinBoundary(boundaryRoot: string, target: string): boolean;
+//# sourceMappingURL=repo-context.d.ts.map

package/dist/core/repo-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-context.d.ts","sourceRoot":"","sources":["../../src/core/repo-context.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAgB/C;AAKD,MAAM,WAAW,UAAU;IAC1B,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAC;IACjB,kGAAkG;IAClG,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,OAAO,CAAC;CACf;AAqDD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,UAAU,CAkBpF;AAED,eAAO,MAAM,iBAAiB;;IAE7B,qFAAqF;;;;;IAKrF,0FAA0F;;;;;;;;;;;;;;;;EAEzF,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,qBAAqB;;IAEjC;;iEAE6D;;;;QAd7D,qFAAqF;;;;;QAKrF,0FAA0F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBzF,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,MAAM,WAAW,OAAO;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,OAAO,EAAE,CAM5D;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE3D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,UAAU,GAAE,WAAW,CAAC,YAAY,CAAe,GACjD,WAAW,CAab;AAED,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAC;AAE7E;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,WAAW,EAAE,EACnB,YAAY,CAAC,EAAE,MAAM,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,EAAE,CAU7C;AAED,sGAAsG;AACtG,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAG9E"}

package/dist/core/repo-context.js

@@ -0,0 +1,204 @@
+// Task-scoped repository context (Phase 5): an on-demand evidence LEDGER, not a retrieval
+// engine. MeowKit resolves a path's owning repository + revision, hashes it for path-scoped
+// freshness, and records/verifies an evidence envelope — the HOST's native tools acquire the
+// content. Retrieved bytes are DATA (never instructions); secret-shaped paths are redacted.
+// Revision is read directly from git refs (no `git` binary), and is PROVENANCE — freshness is
+// per-file-hash, so one repo advancing never marks another repo's untouched evidence stale.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve, relative, isAbsolute, sep } from "node:path";
+import { z } from "zod";
+import { hashFile } from "./compute-checksums.js";
+/**
+ * A path is secret-shaped when ANY of its segments looks like a credential/key store
+ * (mirrors + extends injection-rules Rule 4). Checked per-segment so a `secrets/` or
+ * `.ssh/` directory anywhere in the path is caught, not just the basename.
+ */
+export function isSecretPath(p) {
+    return p.split(/[/\\]/).some((seg) => {
+        const s = seg.toLowerCase();
+        return (s === ".env" ||
+            s.startsWith(".env.") || // .env.local, .env.production, …
+            s === ".npmrc" ||
+            s === ".netrc" ||
+            s === ".ssh" ||
+            s.includes("credential") ||
+            s.includes("secret") ||
+            /(^|[._-])token([._-]|$)/.test(s) || // access_token, token.json — not "tokenizer"
+            /^id_(rsa|dsa|ecdsa|ed25519)$/.test(s) ||
+            /\.(pem|key|keystore|p12|pfx|jks)$/.test(s));
+    });
+}
+/** A resolved git revision must be a hex object id — never arbitrary file content. */
+const SHA_RE = /^[0-9a-f]{7,64}$/;
+/** Resolve the `.git` metadata dir, following a `.git` FILE (worktree/submodule gitdir pointer).
+ * Best-effort: any fs error yields null (revision is provenance, never load-bearing). */
+function resolveGitDir(repoRoot) {
+    try {
+        const dotgit = join(repoRoot, ".git");
+        if (!existsSync(dotgit))
+            return null;
+        if (statSync(dotgit).isDirectory())
+            return dotgit;
+        // `.git` is a file: `gitdir: <path>`
+        const m = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotgit, "utf-8"));
+        if (!m)
+            return null;
+        const gd = m[1].trim();
+        return isAbsolute(gd) ? gd : resolve(repoRoot, gd);
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the HEAD revision from a git metadata dir directly (HEAD → ref → packed-refs). */
+function readHeadRevision(gitDir) {
+    try {
+        return readHeadRevisionUnsafe(gitDir);
+    }
+    catch {
+        return null; // best-effort provenance — a crafted/unreadable repo never crashes resolution
+    }
+}
+function readHeadRevisionUnsafe(gitDir) {
+    const headPath = join(gitDir, "HEAD");
+    if (!existsSync(headPath))
+        return null;
+    const head = readFileSync(headPath, "utf-8").trim();
+    if (head.startsWith("ref:")) {
+        const ref = head.slice(4).trim(); // refs/heads/<branch>
+        const refFile = join(gitDir, ref);
+        // SECURITY: HEAD is untrusted repo DATA. Only return a value that is a hex object id,
+        // and only from a ref file still contained in gitDir — a crafted `ref: ../../etc/passwd`
+        // must never read arbitrary file content into the revision field.
+        if (existsSync(refFile) && isWithinBoundary(gitDir, refFile)) {
+            const sha = readFileSync(refFile, "utf-8").trim();
+            if (SHA_RE.test(sha))
+                return sha;
+        }
+        const packed = join(gitDir, "packed-refs");
+        if (existsSync(packed)) {
+            for (const line of readFileSync(packed, "utf-8").split("\n")) {
+                const m = /^([0-9a-f]{7,64})\s+(.+)$/.exec(line.trim());
+                if (m && m[2] === ref)
+                    return m[1];
+            }
+        }
+        return null;
+    }
+    return SHA_RE.test(head) ? head : null; // detached HEAD
+}
+/**
+ * Resolve the repository that OWNS `absPath` by walking up to the nearest ancestor containing
+ * a `.git` marker (never crossing above `boundaryRoot` when given). A git match yields the repo
+ * root + its HEAD revision; no match yields the boundary root (or the path's dir) as a stable
+ * non-git identity with a null revision — never a fabricated one. Each path resolves to its OWN
+ * nested repo, so a multi-repo parent (e.g. Aspire) is not treated as one repository.
+ */
+export function resolveOwningRepo(absPath, boundaryRoot) {
+    const startDir = existsSync(absPath) && statSync(absPath).isDirectory() ? absPath : dirname(absPath);
+    const boundary = boundaryRoot ? resolve(boundaryRoot) : null;
+    let dir = resolve(startDir);
+    // Defense in depth: never walk a start path that lies outside the boundary (a caller that
+    // skipped the containment gate must not make us climb to an unrelated parent repo).
+    if (boundary && !isWithinBoundary(boundary, dir))
+        return { identity: boundary, revision: null, isGit: false };
+    for (;;) {
+        if (existsSync(join(dir, ".git"))) {
+            const gitDir = resolveGitDir(dir);
+            return { identity: dir, revision: gitDir ? readHeadRevision(gitDir) : null, isGit: true };
+        }
+        if (boundary && dir === boundary)
+            break; // do not cross the boundary
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return { identity: boundary ?? startDir, revision: null, isGit: false };
+}
+export const EvidenceRefSchema = z.object({
+    path: z.string(),
+    /** SHA-256 of the file content at record time, or null when the file was missing. */
+    contentHash: z.string().nullable(),
+    owningRepoIdentity: z.string(),
+    revision: z.string().nullable(),
+    provenance: z.enum(["host-read", "host-search"]).default("host-read"),
+    /** True when the path is secret-shaped and its content must not be persisted verbatim. */
+    redacted: z.boolean().default(false),
+});
+export const ContextEnvelopeSchema = z.object({
+    schemaVersion: z.literal("1.0"),
+    /** The task's scope/container (e.g. an Aspire-style parent holding many repos). It is NOT
+     * itself a repository — each evidence ref names its OWN owning repo + revision. Multi-repo
+     * context is therefore never collapsed into one identity. */
+    boundaryRoot: z.string(),
+    evidence: z.array(EvidenceRefSchema).default([]),
+    queryDescriptor: z.string().default(""),
+    toolDescriptor: z.string().default(""),
+    timestamp: z.string(),
+    omissions: z.array(z.string()).default([]),
+});
+/**
+ * The DISTINCT owning repositories represented in an evidence set, each with its own revision.
+ * This is the multi-repo context view: a task touching several repos under one container (e.g.
+ * Aspire) surfaces every repo separately — no repo's identity/revision is lost or conflated.
+ */
+export function distinctRepos(refs) {
+    const byIdentity = new Map();
+    for (const r of refs)
+        if (!byIdentity.has(r.owningRepoIdentity))
+            byIdentity.set(r.owningRepoIdentity, r.revision);
+    return [...byIdentity]
+        .map(([identity, revision]) => ({ identity, revision }))
+        .sort((a, b) => (a.identity < b.identity ? -1 : a.identity > b.identity ? 1 : 0));
+}
+/** Hash an evidence file for freshness; null when it does not exist (missing evidence). */
+export function hashEvidence(absPath) {
+    return existsSync(absPath) ? hashFile(absPath) : null;
+}
+/**
+ * Build an evidence reference for a path: owning repo + revision, content hash, and a redaction
+ * flag for secret-shaped paths (whose CONTENT must never be persisted — only the hash + flag).
+ */
+export function buildEvidenceRef(absPath, boundaryRoot, provenance = "host-read") {
+    const owner = resolveOwningRepo(absPath, boundaryRoot);
+    const redacted = isSecretPath(absPath);
+    return {
+        path: absPath,
+        // A secret-shaped file is NOT hashed — even a content hash of a low-entropy secret is a
+        // weak confirmation oracle. Its presence is tracked; its content never touches the record.
+        contentHash: redacted ? null : hashEvidence(absPath),
+        owningRepoIdentity: owner.identity,
+        revision: owner.revision,
+        provenance,
+        redacted,
+    };
+}
+/**
+ * Path-scoped freshness: re-hash each recorded evidence path and compare to its recorded hash.
+ * A repo advancing its revision does NOT make untouched files stale — only a changed hash does.
+ *
+ * SECURITY: an envelope is untrusted DATA (it can ship in a third-party repo or be produced by
+ * an injection-tricked agent). When `boundaryRoot` is given, a path outside it is reported
+ * `out-of-scope` and is NEVER stat-ed or hashed — otherwise `check` would become an
+ * existence/hash oracle for arbitrary absolute paths (e.g. `~/.ssh/id_rsa`, `/etc/passwd`).
+ */
+export function checkEvidenceFreshness(refs, boundaryRoot) {
+    return refs.map((ref) => {
+        if (boundaryRoot && !isWithinBoundary(boundaryRoot, ref.path)) {
+            return { path: ref.path, status: "out-of-scope" };
+        }
+        const current = hashEvidence(ref.path);
+        if (current === null)
+            return { path: ref.path, status: "missing" };
+        if (ref.contentHash === null || current !== ref.contentHash)
+            return { path: ref.path, status: "stale" };
+        return { path: ref.path, status: "fresh" };
+    });
+}
+/** True when `target` stays within `boundaryRoot` (lexical; used to reject out-of-scope evidence). */
+export function isWithinBoundary(boundaryRoot, target) {
+    const rel = relative(resolve(boundaryRoot), resolve(target));
+    return rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute(rel);
+}
+//# sourceMappingURL=repo-context.js.map

package/dist/core/repo-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-context.js","sourceRoot":"","sources":["../../src/core/repo-context.ts"],"names":[],"mappings":"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"}

package/dist/core/resolve-capabilities.d.ts

@@ -0,0 +1,70 @@
+import type { CapabilityEntry, ContextRequirement, SupportLevels, TypedRequirement, Verification } from "./capability.js";
+import { type AvailabilityContext, type AvailabilitySnapshot, type AvailabilityStatus } from "./availability.js";
+import { type AcquisitionDescriptor } from "./repo-context-adapter.js";
+import { type LifecycleEvent } from "./provider-lifecycle.js";
+export interface ResolvedCandidate {
+    id: string;
+    kind: string;
+    score: number;
+    reason: string;
+    /** Static per-provider support, or null when that provider has no recorded evidence. */
+    support: SupportLevels | null;
+    requirements: TypedRequirement[];
+    /** Set when the candidate must acquire a task-scoped repo-context envelope before
+     * source-grounded work (Phase 5). The orchestrator — not this pure resolver — acquires it. */
+    contextRequirement: ContextRequirement | null;
+    verification: Verification;
+    /** Runtime invocability is deferred to Phase 3's host snapshot — never asserted here. */
+    invocable: "pending-host-snapshot";
+}
+export interface ResolveResult {
+    intent: string;
+    provider: string | null;
+    candidates: ResolvedCandidate[];
+    /** True when no candidate matched OR the top two are within the near-tie threshold. */
+    ambiguous: boolean;
+}
+/**
+ * Resolve an intent to ranked candidates. Each query term is credited ONCE at its
+ * highest-matching field class (intent > alias > description) — no per-keyword summation,
+ * so keyword multiplicity cannot inflate a score. Authored intents weigh more than
+ * inferred keywords. Order: score desc, then id asc (stable). Zero-score candidates are
+ * dropped; if none remain the result is `ambiguous` with an empty list.
+ */
+export declare function resolveCapabilities(entries: CapabilityEntry[], intent: string, provider?: string | null): ResolveResult;
+/** A resolved candidate enriched with this host's real availability (Phase 3). */
+export interface HostResolvedCandidate extends Omit<ResolvedCandidate, "invocable"> {
+    availability: AvailabilitySnapshot[];
+    /** Rolled-up host invocability — replaces the at-rest `pending-host-snapshot`. */
+    invocable: AvailabilityStatus;
+}
+export interface HostResolveResult {
+    intent: string;
+    provider: string;
+    ambiguous: boolean;
+    /** Selection outcome. `not_needed` is an agent-side decision, never emitted here. */
+    status: "selected" | "ambiguous" | "unavailable" | "unsupported";
+    candidates: HostResolvedCandidate[];
+    /** How THIS provider acquires repo-context evidence (Phase 5 slice 3). Actionable only when
+     * the selected candidate carries a `contextRequirement`; the orchestrator — not MeowKit —
+     * runs the named read/search tools and records the envelope via `context record`. */
+    acquisition: AcquisitionDescriptor;
+    /** Self-auditing provenance (Phase 6 slice 2): which adapter + evidence justified the provider
+     * claims in this result, and the events this provider can actually gate on. */
+    adapterCitation: {
+        provider: string;
+        projectionStatus: string;
+        projectionEvidence: string;
+        gatingEvents: LifecycleEvent[];
+    };
+}
+/**
+ * Resolve an intent AND check this host's real availability for each candidate. Selection
+ * (score-based) and invocability (availability-based) are surfaced SEPARATELY per the
+ * four-levels model: each candidate keeps its own `invocable` verdict, while the top-level
+ * `status` is the aggregate envelope outcome (which does fold in the top candidate's
+ * invocability and support). A provider that does not support the top candidate's surface
+ * → `unsupported`; a top candidate whose requirements are hard-blocked → `unavailable`.
+ */
+export declare function resolveWithHost(entries: CapabilityEntry[], intent: string, ctx: AvailabilityContext): HostResolveResult;
+//# sourceMappingURL=resolve-capabilities.d.ts.map

package/dist/core/resolve-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-capabilities.d.ts","sourceRoot":"","sources":["../../src/core/resolve-capabilities.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,aAAa,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC1H,OAAO,EAGN,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAA4B,KAAK,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEjG,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAc5E,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC;kGAC8F;IAC9F,kBAAkB,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC9C,YAAY,EAAE,YAAY,CAAC;IAC3B,yFAAyF;IACzF,SAAS,EAAE,uBAAuB,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,uFAAuF;IACvF,SAAS,EAAE,OAAO,CAAC;CACnB;AAqBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,GAAG,IAAW,GAAG,aAAa,CA6C7H;AAED,kFAAkF;AAClF,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,WAAW,CAAC;IAClF,YAAY,EAAE,oBAAoB,EAAE,CAAC;IACrC,kFAAkF;IAClF,SAAS,EAAE,kBAAkB,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,qFAAqF;IACrF,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,aAAa,CAAC;IACjE,UAAU,EAAE,qBAAqB,EAAE,CAAC;IACpC;;yFAEqF;IACrF,WAAW,EAAE,qBAAqB,CAAC;IACnC;mFAC+E;IAC/E,eAAe,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,gBAAgB,EAAE,MAAM,CAAC;QACzB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,YAAY,EAAE,cAAc,EAAE,CAAC;KAC/B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,GAAG,iBAAiB,CA+BvH"}

package/dist/core/resolve-capabilities.js

@@ -0,0 +1,124 @@
+import { computeAvailability, rollUpInvocability, } from "./availability.js";
+import { getAcquisitionDescriptor } from "./repo-context-adapter.js";
+import { getProjection } from "./provider-projection.js";
+import { gatingEvents } from "./provider-lifecycle.js";
+// Field-class weights. A query term is credited ONCE at its highest-matching class
+// (never summed across a capability's many keyword strings — that inflates keyword-heavy
+// capabilities). Authored (curated flagship) intents outweigh inferred keywords so a
+// flagship phrase cannot be out-ranked by incidental keyword overlap.
+const WEIGHT_AUTHORED_INTENT = 6;
+const WEIGHT_INFERRED_INTENT = 3;
+const WEIGHT_ALIAS = 2;
+const WEIGHT_TEXT = 1;
+/** A top-two gap strictly below this ⇒ ambiguous (integer scores, so this flags 0- and
+ * 1-point near-ties as ambiguous while an authored-vs-inferred win of ≥3 stays confident). */
+const AMBIGUITY_EPSILON = 2;
+const STOPWORDS = new Set(["the", "a", "an", "to", "of", "in", "on", "this", "that", "for", "and", "or", "my", "me", "it"]);
+/** Normalize free text to a set of lowercase terms (drop punctuation, stopwords, 1-char). */
+function terms(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1 && !STOPWORDS.has(t)));
+}
+/** Union of terms across many field strings (deduped) — the set a query term can match. */
+function fieldTerms(strings) {
+    const out = new Set();
+    for (const s of strings)
+        for (const t of terms(s))
+            out.add(t);
+    return out;
+}
+/**
+ * Resolve an intent to ranked candidates. Each query term is credited ONCE at its
+ * highest-matching field class (intent > alias > description) — no per-keyword summation,
+ * so keyword multiplicity cannot inflate a score. Authored intents weigh more than
+ * inferred keywords. Order: score desc, then id asc (stable). Zero-score candidates are
+ * dropped; if none remain the result is `ambiguous` with an empty list.
+ */
+export function resolveCapabilities(entries, intent, provider = null) {
+    const query = terms(intent);
+    const scored = entries
+        .map((e) => {
+        const intentSet = fieldTerms(e.intents);
+        const aliasSet = fieldTerms(e.aliases);
+        const textSet = fieldTerms([e.whenToUse ?? "", e.description]);
+        const intentWeight = e.provenance.intents === "authored" ? WEIGHT_AUTHORED_INTENT : WEIGHT_INFERRED_INTENT;
+        let intentHits = 0, aliasHits = 0, textHits = 0;
+        for (const q of query) {
+            if (intentSet.has(q))
+                intentHits++;
+            else if (aliasSet.has(q))
+                aliasHits++;
+            else if (textSet.has(q))
+                textHits++;
+        }
+        const score = intentHits * intentWeight + aliasHits * WEIGHT_ALIAS + textHits * WEIGHT_TEXT;
+        const parts = [];
+        if (intentHits)
+            parts.push(`${intentHits} ${e.provenance.intents === "authored" ? "authored " : ""}intent term(s)`);
+        if (aliasHits)
+            parts.push(`${aliasHits} alias term(s)`);
+        if (textHits)
+            parts.push(`${textHits} description term(s)`);
+        return { e, score, reason: parts.length ? `matched ${parts.join(", ")}` : "no term overlap" };
+    })
+        .filter((c) => c.score > 0)
+        .sort((a, b) => (b.score !== a.score ? b.score - a.score : a.e.id < b.e.id ? -1 : 1));
+    const candidates = scored.map(({ e, score, reason }) => ({
+        id: e.id,
+        kind: e.kind,
+        score,
+        reason,
+        support: provider ? e.support[provider] ?? null : null,
+        requirements: e.requirements,
+        contextRequirement: e.contextRequirement,
+        verification: e.verification,
+        invocable: "pending-host-snapshot",
+    }));
+    const ambiguous = candidates.length === 0 ||
+        (candidates.length >= 2 && candidates[0].score - candidates[1].score < AMBIGUITY_EPSILON);
+    return { intent, provider, candidates, ambiguous };
+}
+/**
+ * Resolve an intent AND check this host's real availability for each candidate. Selection
+ * (score-based) and invocability (availability-based) are surfaced SEPARATELY per the
+ * four-levels model: each candidate keeps its own `invocable` verdict, while the top-level
+ * `status` is the aggregate envelope outcome (which does fold in the top candidate's
+ * invocability and support). A provider that does not support the top candidate's surface
+ * → `unsupported`; a top candidate whose requirements are hard-blocked → `unavailable`.
+ */
+export function resolveWithHost(entries, intent, ctx) {
+    const byId = new Map(entries.map((e) => [e.id, e]));
+    const base = resolveCapabilities(entries, intent, ctx.provider);
+    const candidates = base.candidates.map((c) => {
+        const entry = byId.get(c.id);
+        const availability = entry ? computeAvailability(entry, ctx) : [];
+        // Spread-override the at-rest `pending-host-snapshot` invocable with the host verdict.
+        return { ...c, availability, invocable: rollUpInvocability(availability) };
+    });
+    let status;
+    if (candidates.length === 0)
+        status = "unavailable";
+    else if (base.ambiguous)
+        status = "ambiguous";
+    else if (candidates[0].support && candidates[0].support.discoverable === false)
+        status = "unsupported";
+    else
+        status = candidates[0].invocable === "unavailable" ? "unavailable" : "selected";
+    return {
+        intent: base.intent,
+        provider: ctx.provider,
+        ambiguous: base.ambiguous,
+        status,
+        candidates,
+        acquisition: getAcquisitionDescriptor(ctx.provider),
+        adapterCitation: {
+            provider: ctx.provider,
+            projectionStatus: getProjection(ctx.provider).status,
+            projectionEvidence: getProjection(ctx.provider).evidence,
+            gatingEvents: gatingEvents(ctx.provider),
+        },
+    };
+}
+//# sourceMappingURL=resolve-capabilities.js.map