@retinue/agentkit 0.1.0 → 0.3.0

package/dist/server/cli.js

@@ -35,15 +35,18 @@ export const runApiHost = async (env = process.env) => {
     // twice: `loadConfig` is pure and `boot` validates again.
     loadConfig(env);
     const app = await loadApp(env);
-    const { config, sql } = await boot({
+    const { config, sql, runner } = await boot({
         env,
         connect: async (loaded) => {
             const { Pool } = await import("pg");
-            const { createPgExecutor } = await import("../entries/adapters-postgres.js");
-            return { sql: createPgExecutor(new Pool({ connectionString: loaded.databaseUrl })) };
+            const { createPgExecutor, createPoolOpener } = await import("../entries/adapters-postgres.js");
+            const pool = new Pool({ connectionString: loaded.databaseUrl });
+            // `open` is what lets `boot` build a transaction scope. Without it the API host had no runner and
+            // `sendMessage` could not claim a conversation — #254.
+            return { sql: createPgExecutor(pool), open: createPoolOpener(pool) };
         },
     });
-    const deps = await app.deps({ config, sql });
+    const deps = await app.deps({ config, sql, ...(runner === undefined ? {} : { runner }) });
     const { createSchemaManager } = await import("../entries/adapters-postgres.js");
     const probes = [postgresProbe(sql), schemaProbe(createSchemaManager(sql))];
     if (app.redis)

package/dist/server/doctor.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `retinue doctor` — task #252 AC-4.
+ *
+ * The one command here that is new rather than a wrapper, and the one that pays for itself: every failure it
+ * names is otherwise a support conversation. A deployment that will not start currently produces one error, from
+ * whichever check happened to run first, and the operator fixes it and runs again to find the next.
+ *
+ * ## Every failure, not the first
+ *
+ * The whole value is in the plural. A doctor that stops at the first problem sends the user round the loop once
+ * per problem — which is exactly what starting the server already does, so it would add nothing. Each check is
+ * therefore independent and its own failure is caught, so a Postgres that will not connect does not prevent the
+ * Redis check from running.
+ *
+ * ## Nothing here prints a secret
+ *
+ * A diagnostic tool is exactly where a URL with a password in it gets pasted into a support ticket. So a
+ * connection string is reported by its *shape* — host and database, never userinfo — and a failure message is
+ * the driver's, scrubbed. `mcp/egress.ts` already refuses credentials in a URL for the same reason.
+ */
+export type CheckResult = {
+    readonly name: string;
+    readonly ok: boolean;
+    /** What was found. Never a secret. */
+    readonly detail: string;
+    /** Present when `ok` is false: what to do about it. */
+    readonly remedy?: string;
+    /**
+     * A check that could not run rather than one that failed.
+     *
+     * Distinct because the two need different responses: a failed check is a broken deployment, and a skipped one
+     * is a deployment this tool cannot see into. Reporting a skip as a pass would be the "passes having checked
+     * nothing" failure; reporting it as a failure would tell an operator to fix something that is not wrong.
+     */
+    readonly skipped?: boolean;
+};
+export declare const describeUrl: (value: string) => string;
+/** The driver's message, with anything URL-shaped reduced. Errors quote the connection string routinely. */
+export declare const scrub: (message: string) => string;
+export type DoctorDeps = {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Injected so the checks are testable without a database or a Redis. */
+    readonly connectPostgres?: (url: string) => Promise<{
+        query(text: string, params?: readonly unknown[]): Promise<unknown>;
+        end(): Promise<void>;
+    }>;
+    readonly connectRedis?: (url: string) => Promise<{
+        ping(): Promise<string>;
+        quit(): Promise<unknown>;
+    }>;
+    readonly schemaVersions?: (sql: {
+        query(text: string, params?: readonly unknown[]): Promise<unknown>;
+    }) => Promise<{
+        current: number;
+        target: number;
+    }>;
+};
+/** How long any one check may take before it is reported as a timeout. */
+export declare const CHECK_TIMEOUT_MS = 5000;
+/**
+ * A backstop, because **a diagnostic that hangs is worse than one that fails.**
+ *
+ * Found by running `doctor` against a refused port: `pg.Pool` has no default connect timeout and `ioredis`
+ * retries a refused connection for ever, so the command sat there silently instead of reporting the two
+ * failures it existed to report. Both drivers are now configured to fail fast, and this is the belt to that
+ * braces — a driver whose timeout option is wrong or renamed must not be able to hang the tool.
+ *
+ * The timer is unref'd so a completed check never holds the process open past its work.
+ */
+export declare const withTimeout: <T>(what: string, work: Promise<T>, ms?: number) => Promise<T>;
+export declare const runChecks: (deps?: DoctorDeps) => Promise<readonly CheckResult[]>;
+/** Human output. Returns the exit code, so the caller does not decide what a failure means. */
+export declare const report: (results: readonly CheckResult[], write?: (line: string) => void) => number;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/server/doctor.js

@@ -0,0 +1,280 @@
+/**
+ * `retinue doctor` — task #252 AC-4.
+ *
+ * The one command here that is new rather than a wrapper, and the one that pays for itself: every failure it
+ * names is otherwise a support conversation. A deployment that will not start currently produces one error, from
+ * whichever check happened to run first, and the operator fixes it and runs again to find the next.
+ *
+ * ## Every failure, not the first
+ *
+ * The whole value is in the plural. A doctor that stops at the first problem sends the user round the loop once
+ * per problem — which is exactly what starting the server already does, so it would add nothing. Each check is
+ * therefore independent and its own failure is caught, so a Postgres that will not connect does not prevent the
+ * Redis check from running.
+ *
+ * ## Nothing here prints a secret
+ *
+ * A diagnostic tool is exactly where a URL with a password in it gets pasted into a support ticket. So a
+ * connection string is reported by its *shape* — host and database, never userinfo — and a failure message is
+ * the driver's, scrubbed. `mcp/egress.ts` already refuses credentials in a URL for the same reason.
+ */
+import { ConfigurationError, loadConfig } from "./config.js";
+/**
+ * A connection string reduced to what is safe to print.
+ *
+ * Deliberately not a regex over the whole string: `URL` parsing means a password containing a `@` or a `/`
+ * cannot smuggle itself into the output. An unparseable value is reported as unparseable rather than echoed,
+ * because echoing it is how a secret reaches a log.
+ */
+/**
+ * A connection string reduced to what is safe to print, by **whitelist**.
+ *
+ * Two earlier versions of this leaked, and both leaked the same way — by trying to *remove* the secret from a
+ * string whose structure was not what they assumed:
+ *
+ * 1. Parsing with `URL` and printing `hostname`/`port`/`pathname`. For
+ *    `postgres://user:p@ss/word@db.internal:5432/app`, `URL` reads `user:p` as the userinfo and `ss` as the
+ *    hostname, so the "safe" output was `postgres://ss/word@db.internal:5432/app` — half the password, spread
+ *    across the host and path.
+ * 2. Refusing when the *authority* contained two `@`. The authority ends at the first `/`, and in that example
+ *    the second `@` is after it. So the check passed and the leak stood.
+ *
+ * A redaction function must therefore not try to find the secret. It matches a strict, unambiguous shape and
+ * prints only the groups it captured; anything else is refused unprinted. An unescaped `@` or `/` in a password
+ * is common, and it is exactly what makes a connection string ambiguous — so ambiguity is the thing to refuse,
+ * not to parse harder.
+ */
+const SAFE_URL = /^([a-z][a-z0-9+.-]*):\/\/(?:[^@/?#]*@)?([A-Za-z0-9._-]+|\[[0-9A-Fa-f:]+\])(?::(\d+))?(?:\/([A-Za-z0-9._-]*))?$/;
+export const describeUrl = (value) => {
+    const match = SAFE_URL.exec(value);
+    if (match === null)
+        return "(not printed — the value does not match an unambiguous connection-string shape)";
+    const [, scheme, host, port, database] = match;
+    return `${scheme}://${host}${port === undefined ? "" : `:${port}`}${database ? `/${database}` : ""}`;
+};
+/** The driver's message, with anything URL-shaped reduced. Errors quote the connection string routinely. */
+export const scrub = (message) => message.replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s'"]+/gi, (m) => describeUrl(m));
+const message = (error) => scrub(error instanceof Error ? error.message : String(error));
+/** True when `describeUrl` refused to print a value, so nothing derived from it can be trusted either. */
+const unsafe = (described) => described.startsWith("(");
+/**
+ * What to say about a connection failure — the URL and the driver's message, or neither.
+ *
+ * A driver interpolates whatever *it* parsed, so `postgres://u:p@ss/word@host/db` fails with
+ * `getaddrinfo ENOTFOUND ss` — a fragment of the password, in a message no scrubber can recognise as one
+ * because `ss` is not URL-shaped. The rule that follows is simple and the only safe one: if the value could not
+ * be printed, the error derived from it is not printed either. The remedy still names the variable, which is
+ * what the operator needs.
+ */
+const failureDetail = (url, error) => {
+    const described = describeUrl(url);
+    return unsafe(described)
+        ? `${described} The driver's message is withheld for the same reason — it can quote the value it parsed.`
+        : `${described}: ${message(error)}`;
+};
+/** How long any one check may take before it is reported as a timeout. */
+export const CHECK_TIMEOUT_MS = 5_000;
+/**
+ * A backstop, because **a diagnostic that hangs is worse than one that fails.**
+ *
+ * Found by running `doctor` against a refused port: `pg.Pool` has no default connect timeout and `ioredis`
+ * retries a refused connection for ever, so the command sat there silently instead of reporting the two
+ * failures it existed to report. Both drivers are now configured to fail fast, and this is the belt to that
+ * braces — a driver whose timeout option is wrong or renamed must not be able to hang the tool.
+ *
+ * The timer is unref'd so a completed check never holds the process open past its work.
+ */
+export const withTimeout = async (what, work, ms = CHECK_TIMEOUT_MS) => {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`${what} did not respond within ${ms}ms`)), ms);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+};
+export const runChecks = async (deps = {}) => {
+    const env = deps.env ?? process.env;
+    const results = [];
+    // 1. Configuration. Everything else needs it, so a failure here skips the rest rather than reporting
+    //    cascading failures that are all the same problem.
+    let config;
+    try {
+        config = loadConfig(env);
+        results.push({ name: "configuration", ok: true, detail: `schema mode ${config.schemaMode}, port ${config.port}` });
+    }
+    catch (error) {
+        results.push({
+            name: "configuration",
+            ok: false,
+            detail: message(error),
+            remedy: error instanceof ConfigurationError
+                ? `Set or correct: ${error.variables.join(", ")}. See .env.example.`
+                : "See .env.example for the variables this deployment needs.",
+        });
+        for (const name of ["postgres", "schema", "redis"]) {
+            results.push({
+                name,
+                ok: true,
+                skipped: true,
+                detail: "not checked — configuration is unusable, so this would fail for the same reason",
+            });
+        }
+        return results;
+    }
+    // 2. The app module, which `serve` and `worker` need and `migrate` does not.
+    const appModule = env["RETINUE_APP_MODULE"];
+    if (appModule === undefined || appModule.trim() === "") {
+        results.push({
+            name: "app module",
+            ok: true,
+            skipped: true,
+            detail: "RETINUE_APP_MODULE is unset — `migrate` and `doctor` work without it; `serve` and `worker` do not",
+            remedy: "Point RETINUE_APP_MODULE at a module default-exporting { authenticate, deps } before serving.",
+        });
+    }
+    else {
+        try {
+            const loaded = (await import(appModule));
+            const app = loaded.default;
+            const ok = typeof app?.authenticate === "function" && typeof app?.deps === "function";
+            results.push({
+                name: "app module",
+                ok,
+                detail: ok ? `${appModule} exports { authenticate, deps }` : `${appModule} loaded but is missing exports`,
+                ...(ok ? {} : { remedy: "It must default-export { authenticate, deps }. `authenticate` has no default." }),
+            });
+        }
+        catch (error) {
+            results.push({
+                name: "app module",
+                ok: false,
+                detail: `${appModule} could not be loaded: ${message(error)}`,
+                remedy: "Check the path is resolvable from the working directory, and that the module builds.",
+            });
+        }
+    }
+    // 3. Postgres, and 4. the schema — one connection, two findings.
+    const connectPostgres = deps.connectPostgres;
+    if (connectPostgres === undefined) {
+        results.push({ name: "postgres", ok: true, skipped: true, detail: "no driver supplied" });
+        results.push({ name: "schema", ok: true, skipped: true, detail: "no driver supplied" });
+    }
+    else {
+        let sql;
+        /**
+         * Whether Postgres *answered*, which is not the same as whether a pool object exists.
+         *
+         * `new Pool()` does not connect, so `sql` is defined even when the database is unreachable — and keying the
+         * schema check on `sql !== undefined` reported "0 of 30 migrations applied → Run `retinue migrate`" against
+         * a database nobody could reach. That is a diagnostic sending an operator to fix the wrong thing, which is
+         * worse than reporting nothing.
+         */
+        let reachable = false;
+        try {
+            sql = await withTimeout("postgres", connectPostgres(config.databaseUrl));
+            await withTimeout("postgres", sql.query("select 1"));
+            reachable = true;
+            results.push({ name: "postgres", ok: true, detail: `reachable at ${describeUrl(config.databaseUrl)}` });
+        }
+        catch (error) {
+            results.push({
+                name: "postgres",
+                ok: false,
+                detail: failureDetail(config.databaseUrl, error),
+                remedy: "Check the database is running and RETINUE_DATABASE_URL points at it.",
+            });
+        }
+        if (reachable && sql !== undefined && deps.schemaVersions !== undefined) {
+            try {
+                const { current, target } = await withTimeout("schema", deps.schemaVersions(sql));
+                // Ahead is reported as a failure, not a pass: a database migrated by a newer build than this one is a
+                // deployment about to behave unpredictably, and "current >= target" would call it healthy.
+                const ok = current === target;
+                results.push({
+                    name: "schema",
+                    ok,
+                    detail: `${current} of ${target} migrations applied`,
+                    ...(ok
+                        ? {}
+                        : {
+                            remedy: current < target
+                                ? "Run `retinue migrate`."
+                                : "This database is ahead of this build. Deploy the matching version rather than migrating down.",
+                        }),
+                });
+            }
+            catch (error) {
+                results.push({
+                    name: "schema",
+                    ok: false,
+                    detail: message(error),
+                    remedy: "Run `retinue migrate --status` for detail.",
+                });
+            }
+        }
+        else if (reachable) {
+            results.push({ name: "schema", ok: true, skipped: true, detail: "no schema reader supplied" });
+        }
+        else {
+            results.push({
+                name: "schema",
+                ok: true,
+                skipped: true,
+                detail: "not checked — Postgres is unreachable, so this would fail for the same reason",
+            });
+        }
+        if (sql !== undefined)
+            await sql.end().catch(() => undefined);
+    }
+    // 5. Redis.
+    if (deps.connectRedis === undefined) {
+        results.push({ name: "redis", ok: true, skipped: true, detail: "no client supplied" });
+    }
+    else {
+        let redis;
+        try {
+            redis = await withTimeout("redis", deps.connectRedis(config.redisUrl));
+            const pong = await withTimeout("redis", redis.ping());
+            results.push({ name: "redis", ok: true, detail: `reachable at ${describeUrl(config.redisUrl)} (${pong})` });
+        }
+        catch (error) {
+            results.push({
+                name: "redis",
+                ok: false,
+                detail: failureDetail(config.redisUrl, error),
+                remedy: "Check Redis is running and RETINUE_REDIS_URL points at it.",
+            });
+        }
+        finally {
+            // Always, including after a failure. Leaving a client open kept the socket handle alive and the command
+            // never exited — a diagnostic that reports correctly and then hangs is still a diagnostic that hangs.
+            if (redis !== undefined)
+                await redis.quit().catch(() => undefined);
+        }
+    }
+    return results;
+};
+/** Human output. Returns the exit code, so the caller does not decide what a failure means. */
+export const report = (results, write = console.log) => {
+    const failed = results.filter((r) => !r.ok);
+    for (const r of results) {
+        const mark = !r.ok ? "✗" : r.skipped === true ? "–" : "✓";
+        write(`${mark} ${r.name}: ${r.detail}`);
+        if (r.remedy !== undefined)
+            write(`    → ${r.remedy}`);
+    }
+    write("");
+    write(failed.length === 0
+        ? `✓ ${results.filter((r) => r.skipped !== true).length} check(s) passed`
+        : `✗ ${failed.length} of ${results.length} check(s) failed`);
+    return failed.length === 0 ? 0 : 1;
+};
+//# sourceMappingURL=doctor.js.map

package/dist/skills/catalogue.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A token ceiling on the skill catalogue — REQ-045 (#204), task #210, AC-5.
+ *
+ * Skills have exactly the tool catalogue's problem: a compact entry per skill sits in context on every turn, and
+ * the bodies already load on demand, so what is left is linear in how many skills a tenant has. 25 skills at
+ * `descriptionMaxLength` is a page of prompt before the conversation starts.
+ *
+ * The budget is `core/budget.ts` — the same one the tool catalogue uses, not a second copy.
+ *
+ * ## The notice is part of the catalogue, not part of the log
+ *
+ * The tool path can be loud in a run event because the engine assembles the tool list and the engine owns the
+ * event stream. The skill catalogue is assembled by a *context provider*, which has no event stream, so the same
+ * report reaches the same place by a different route: `truncationNotice` puts it in the text the model reads.
+ *
+ * That is arguably the stronger channel of the two. A run event tells whoever reviews the run afterwards; this
+ * tells the model *during* the turn, so it can say "there are more skills than I was shown" instead of
+ * confidently reporting that no skill exists for the job. Callers still get the report, and a host with an event
+ * stream to hand should log it too.
+ */
+/**
+ * The specific core modules, **not** `core/index.js`.
+ *
+ * The barrel re-exports `core/validation.ts`, which imports `zod`. Importing it from here put zod into the
+ * dependency graph of `@retinue/agentkit/persistence` — a subpath whose whole claim is that it reaches nothing
+ * outside the standard library, so a test or a prototype needs no install beyond the package. Caught by
+ * `root-import-weight.test.ts`, which walks the graph transitively; a barrel import is how that guarantee gets
+ * lost, and it is invisible in review.
+ */
+import { type BudgetOutcome, type TokenBudget } from "../core/budget.js";
+import type { SkillCatalogEntry } from "./index.js";
+/**
+ * Per-entry scaffolding: the bullet, the name emphasis, the version.
+ *
+ * Slightly larger than the tool catalogue's because a skill entry is rendered as prose in Markdown rather than
+ * as a JSON tool definition.
+ */
+export declare const SKILL_ENTRY_OVERHEAD_TOKENS = 8;
+export declare const skillEntryTokens: (entry: SkillCatalogEntry) => number;
+export declare const budgetSkillCatalogue: (entries: readonly SkillCatalogEntry[], budget: TokenBudget) => BudgetOutcome<SkillCatalogEntry>;
+/**
+ * What the model is told when the catalogue was shortened.
+ *
+ * Names the skills rather than counting them, for the same reason the run event does: "3 more skills exist" is
+ * something a model can only ignore, while a name is something it can ask for. Empty string when nothing was
+ * dropped, so a caller can concatenate unconditionally.
+ */
+export declare const truncationNotice: (outcome: BudgetOutcome<SkillCatalogEntry>) => string;
+//# sourceMappingURL=catalogue.d.ts.map

package/dist/skills/catalogue.js

@@ -0,0 +1,61 @@
+/**
+ * A token ceiling on the skill catalogue — REQ-045 (#204), task #210, AC-5.
+ *
+ * Skills have exactly the tool catalogue's problem: a compact entry per skill sits in context on every turn, and
+ * the bodies already load on demand, so what is left is linear in how many skills a tenant has. 25 skills at
+ * `descriptionMaxLength` is a page of prompt before the conversation starts.
+ *
+ * The budget is `core/budget.ts` — the same one the tool catalogue uses, not a second copy.
+ *
+ * ## The notice is part of the catalogue, not part of the log
+ *
+ * The tool path can be loud in a run event because the engine assembles the tool list and the engine owns the
+ * event stream. The skill catalogue is assembled by a *context provider*, which has no event stream, so the same
+ * report reaches the same place by a different route: `truncationNotice` puts it in the text the model reads.
+ *
+ * That is arguably the stronger channel of the two. A run event tells whoever reviews the run afterwards; this
+ * tells the model *during* the turn, so it can say "there are more skills than I was shown" instead of
+ * confidently reporting that no skill exists for the job. Callers still get the report, and a host with an event
+ * stream to hand should log it too.
+ */
+/**
+ * The specific core modules, **not** `core/index.js`.
+ *
+ * The barrel re-exports `core/validation.ts`, which imports `zod`. Importing it from here put zod into the
+ * dependency graph of `@retinue/agentkit/persistence` — a subpath whose whole claim is that it reaches nothing
+ * outside the standard library, so a test or a prototype needs no install beyond the package. Caught by
+ * `root-import-weight.test.ts`, which walks the graph transitively; a barrel import is how that guarantee gets
+ * lost, and it is invisible in review.
+ */
+import { applyTokenBudget } from "../core/budget.js";
+import { estimateTokens } from "../core/tokens.js";
+/**
+ * Per-entry scaffolding: the bullet, the name emphasis, the version.
+ *
+ * Slightly larger than the tool catalogue's because a skill entry is rendered as prose in Markdown rather than
+ * as a JSON tool definition.
+ */
+export const SKILL_ENTRY_OVERHEAD_TOKENS = 8;
+export const skillEntryTokens = (entry) => estimateTokens(`${entry.name} v${entry.version} ${entry.description}`) + SKILL_ENTRY_OVERHEAD_TOKENS;
+export const budgetSkillCatalogue = (entries, budget) => applyTokenBudget({
+    items: entries,
+    budget,
+    tokensOf: skillEntryTokens,
+    nameOf: (entry) => entry.name,
+});
+/**
+ * What the model is told when the catalogue was shortened.
+ *
+ * Names the skills rather than counting them, for the same reason the run event does: "3 more skills exist" is
+ * something a model can only ignore, while a name is something it can ask for. Empty string when nothing was
+ * dropped, so a caller can concatenate unconditionally.
+ */
+export const truncationNotice = (outcome) => outcome.dropped.length === 0
+    ? ""
+    : [
+        "",
+        `Not every skill is listed above: ${outcome.dropped.length} more exist but did not fit this turn's`,
+        `catalogue budget (${outcome.dropped.join(", ")}). If one of them is what the task needs, say so rather`,
+        "than concluding there is no skill for it.",
+    ].join("\n");
+//# sourceMappingURL=catalogue.js.map

package/dist/skills/context.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Skills in context — task #244, the interpreter for `AgentManifest.skillPolicy`.
+ *
+ * `skillPolicy` was declared and read by nothing. That was not one missing line: the *subsystem* was complete and
+ * unreachable. `SkillResolver.listCatalog` already takes `{ tenantId, assigned, allowTenantSkills }` — the
+ * manifest's two fields verbatim — the store had memory and Postgres adapters under a conformance suite, and
+ * `ContextKind`/`ContextBudget` already reserved a `skills` bucket for a section nothing produced. Two things
+ * were missing: something to emit that section, and an implementation of `load_skill` (see
+ * `tools/registry.ts`).
+ *
+ * ## Why the catalogue and not the bodies
+ *
+ * A skill body is up to 20,000 characters (`SKILL_LIMITS.instructionsMaxLength`). Twenty-five of those is a
+ * context window. So the section lists **names and descriptions**, and the model calls `load_skill` for the one
+ * it wants — the same two-tier shape the tool catalogue uses, for the same reason.
+ *
+ * ## Origin is `platform`, and the interpolated values are neutralised
+ *
+ * A skill body may instruct the agent — that is what a skill *is* — so this section is `platform` rather than
+ * `external`. But a *tenant-authored* skill's name and description are written by a customer, and this section
+ * carries them. Wrapping the whole section in an untrusted envelope would say "nothing in here is an
+ * instruction", which is false and would break skills; so the section stays `platform` and neutralises the
+ * values it interpolates, which is exactly the case `ContextSection.origin`'s own documentation describes.
+ */
+import type { ContextProvider } from "../context/index.js";
+import { type SkillResolver } from "./index.js";
+import type { SkillBodyLoader } from "../tools/registry.js";
+/** The provider id a manifest names in `contextProviderIds`. */
+export declare const SKILL_CATALOGUE_PROVIDER_ID = "skill-catalogue";
+/**
+ * Strips what could end a delimited block or forge a heading in the rendered prompt.
+ *
+ * Narrow on purpose: a skill description is prose a customer wrote, and mangling it would make the catalogue
+ * unreadable. Newlines go because the section is one line per skill and a description containing a line break
+ * could otherwise invent a row; backticks and the sequences that open a fenced block go because the surrounding
+ * render uses them structurally.
+ */
+export declare const neutralise: (value: string) => string;
+export declare const createSkillCatalogueProvider: (deps: {
+    readonly resolver: SkillResolver;
+    readonly policy: {
+        readonly assigned: readonly string[];
+        readonly allowTenantSkills: boolean;
+    };
+}) => ContextProvider;
+/**
+ * Adapts a `SkillResolver` to the registry's structural `SkillBodyLoader`.
+ *
+ * The version is not a parameter. `loadBody` pins to an exact version so a mid-run edit cannot change behaviour,
+ * and the version the model should get is the one the catalogue it just read advertised — so it is looked up
+ * here rather than trusted from the model's arguments. A model naming a version would be a model choosing which
+ * revision of an instruction to follow.
+ */
+export declare const createSkillBodyLoader: (deps: {
+    readonly resolver: SkillResolver;
+    readonly policy: {
+        readonly assigned: readonly string[];
+        readonly allowTenantSkills: boolean;
+    };
+}) => SkillBodyLoader;
+//# sourceMappingURL=context.d.ts.map

package/dist/skills/context.js

@@ -0,0 +1,107 @@
+/**
+ * Skills in context — task #244, the interpreter for `AgentManifest.skillPolicy`.
+ *
+ * `skillPolicy` was declared and read by nothing. That was not one missing line: the *subsystem* was complete and
+ * unreachable. `SkillResolver.listCatalog` already takes `{ tenantId, assigned, allowTenantSkills }` — the
+ * manifest's two fields verbatim — the store had memory and Postgres adapters under a conformance suite, and
+ * `ContextKind`/`ContextBudget` already reserved a `skills` bucket for a section nothing produced. Two things
+ * were missing: something to emit that section, and an implementation of `load_skill` (see
+ * `tools/registry.ts`).
+ *
+ * ## Why the catalogue and not the bodies
+ *
+ * A skill body is up to 20,000 characters (`SKILL_LIMITS.instructionsMaxLength`). Twenty-five of those is a
+ * context window. So the section lists **names and descriptions**, and the model calls `load_skill` for the one
+ * it wants — the same two-tier shape the tool catalogue uses, for the same reason.
+ *
+ * ## Origin is `platform`, and the interpolated values are neutralised
+ *
+ * A skill body may instruct the agent — that is what a skill *is* — so this section is `platform` rather than
+ * `external`. But a *tenant-authored* skill's name and description are written by a customer, and this section
+ * carries them. Wrapping the whole section in an untrusted envelope would say "nothing in here is an
+ * instruction", which is false and would break skills; so the section stays `platform` and neutralises the
+ * values it interpolates, which is exactly the case `ContextSection.origin`'s own documentation describes.
+ */
+import { estimateTokens } from "../core/tokens.js";
+import { SKILL_LIMITS } from "./index.js";
+/** The provider id a manifest names in `contextProviderIds`. */
+export const SKILL_CATALOGUE_PROVIDER_ID = "skill-catalogue";
+/**
+ * Strips what could end a delimited block or forge a heading in the rendered prompt.
+ *
+ * Narrow on purpose: a skill description is prose a customer wrote, and mangling it would make the catalogue
+ * unreadable. Newlines go because the section is one line per skill and a description containing a line break
+ * could otherwise invent a row; backticks and the sequences that open a fenced block go because the surrounding
+ * render uses them structurally.
+ */
+export const neutralise = (value) => value
+    .replace(/[\r\n]+/g, " ")
+    .replace(/```+/g, "'''")
+    .replace(/[`]/g, "'")
+    .trim();
+export const createSkillCatalogueProvider = (deps) => ({
+    id: SKILL_CATALOGUE_PROVIDER_ID,
+    async provide(context) {
+        const entries = await deps.resolver.listCatalog({
+            tenantId: context.tenantId,
+            assigned: deps.policy.assigned,
+            allowTenantSkills: deps.policy.allowTenantSkills,
+        });
+        // No section at all rather than an empty one. A heading saying "Skills" over nothing tells the model it has
+        // a capability and then shows it none, which is worse than silence — and it would still cost tokens.
+        if (entries.length === 0)
+            return [];
+        const lines = entries.map((e) => `- \`${neutralise(e.name)}\` — ${neutralise(e.description)}`);
+        const body = [
+            `You have ${entries.length} skill${entries.length === 1 ? "" : "s"} available. Each is a set of`,
+            "instructions for a particular kind of task. Read the list, and when one applies call",
+            "`load_skill` with its name to get the full instructions before you start.",
+            `You may load at most ${SKILL_LIMITS.maxLoadedPerRun} in a single run, so choose.`,
+            "",
+            ...lines,
+        ].join("\n");
+        return [
+            {
+                providerId: SKILL_CATALOGUE_PROVIDER_ID,
+                title: "Skills",
+                body,
+                // Above ordinary user context: a skill changes *how* the agent works, so it should survive pruning
+                // longer than the material it works on.
+                priority: 70,
+                estimatedTokens: estimateTokens(body),
+                provenance: "skill catalogue",
+                sensitivity: "internal",
+                // See the header: the section may instruct, and the customer-authored values inside it are neutralised
+                // rather than the whole section being disclaimed.
+                origin: "platform",
+                cacheable: true,
+                kind: "skills",
+            },
+        ];
+    },
+});
+/**
+ * Adapts a `SkillResolver` to the registry's structural `SkillBodyLoader`.
+ *
+ * The version is not a parameter. `loadBody` pins to an exact version so a mid-run edit cannot change behaviour,
+ * and the version the model should get is the one the catalogue it just read advertised — so it is looked up
+ * here rather than trusted from the model's arguments. A model naming a version would be a model choosing which
+ * revision of an instruction to follow.
+ */
+export const createSkillBodyLoader = (deps) => ({
+    async load(context, name) {
+        const entries = await deps.resolver.listCatalog({
+            tenantId: context.tenantId,
+            assigned: deps.policy.assigned,
+            allowTenantSkills: deps.policy.allowTenantSkills,
+        });
+        // Resolved against the catalogue *this* agent may see, so `assigned` and `allowTenantSkills` gate loading
+        // and not merely listing. A policy that filtered the list but not the load would be no policy at all.
+        const entry = entries.find((e) => e.name === name);
+        if (entry === undefined)
+            return null;
+        const version = await deps.resolver.loadBody({ tenantId: context.tenantId, name, version: entry.version });
+        return { name: version.name, version: version.version, instructions: version.instructions };
+    },
+});
+//# sourceMappingURL=context.js.map