@retinue/agentkit 0.2.0 → 0.3.1

package/dist/server/pool.js

@@ -0,0 +1,73 @@
+/**
+ * The one place a `pg.Pool` is built for this host — REQ-041 (#190).
+ *
+ * There were four: `bin.ts` for `migrate`/`doctor`, `cli.ts` for the API host, `cli-worker.ts` for the
+ * worker, and the driver `doctor` is handed. Four copies of "how this deployment connects" is three
+ * copies too many, and the one that drifts is the one nobody exercises — the worker, whose writes are
+ * the ones that must land in the same schema as everything else.
+ *
+ * **What it adds over `new Pool`.** `RETINUE_DATABASE_SCHEMA` names the schema the platform's tables
+ * live in, and honouring it takes two things that must agree:
+ *
+ *  - `pool.on("connect")` sets `search_path` on **every** connection, because `createPgExecutor` runs
+ *    each query through `pool.query`, which takes a different connection per call. A pooled connection
+ *    carries whatever `search_path` its last user left, so setting it once at startup means the first
+ *    few statements land in the right schema and the rest land wherever. That failure is not loud: it
+ *    is a table created in `public` by a migration that reported success.
+ *  - `createPoolOpener(pool, …)` sets it again per checkout, which is what the transaction scope uses.
+ *    Redundant on paper and deliberately kept: the opener is the path that holds `SELECT … FOR UPDATE`
+ *    across statements, and it must not depend on a listener having fired.
+ *
+ * **`public` stays on the path** after the named schema. Two things need it: the `vector` type is
+ * pinned to `public` so it resolves from any schema (see the note in `migrations.ts`), and ShareFlow's
+ * adapters qualify all 70 of their queries as `public.`, which is what lets one pool serve a platform
+ * schema and a product schema at once.
+ */
+/**
+ * The `search_path` for a named schema, or `undefined` to leave the connection's own.
+ *
+ * Exported because it is the only string in this file that ends up in SQL, and a test that pins it is
+ * cheaper than reading two call sites to find out what a deployment actually gets.
+ */
+export const searchPathFor = (schema) => schema === undefined || schema === "" ? undefined : `${schema}, public`;
+export const openPostgres = async (settings) => {
+    const { Pool } = await import("pg");
+    const { createPgExecutor, createPoolOpener } = await import("../entries/adapters-postgres.js");
+    const searchPath = searchPathFor(settings.databaseSchema);
+    const pool = new Pool({
+        connectionString: settings.databaseUrl,
+        ...(settings.connectionTimeoutMillis === undefined
+            ? {}
+            : { connectionTimeoutMillis: settings.connectionTimeoutMillis }),
+    });
+    if (searchPath !== undefined) {
+        /**
+         * Queued on the client, not awaited — which is what makes it correct rather than racy.
+         *
+         * node-postgres queues queries per client in order, so this `SET` is ahead of whatever the borrower
+         * runs next on that same connection. An `await` here would have nothing to attach to: `connect` is
+         * an event, and the pool hands the client out regardless of what a listener is still doing.
+         *
+         * A failure is surfaced rather than swallowed, and it is worth being precise about what it can and
+         * cannot catch. It means the role may not *use* the schema. It does **not** mean the schema is
+         * missing: `SET search_path TO retinue, public` succeeds when `retinue` does not exist, because a
+         * missing entry is skipped rather than rejected, and every write then lands in `public` with no
+         * error anywhere. Nothing at this layer can see that — which is why `retinue migrate` creates the
+         * schema before anything connects, and why this listener is not the guard against it.
+         */
+        pool.on("connect", (client) => {
+            void client.query(`SET search_path TO ${searchPath}`).catch((error) => {
+                client.end();
+                pool.emit("error", error instanceof Error
+                    ? new Error(`could not SET search_path TO ${searchPath}: ${error.message}`, { cause: error })
+                    : new Error(`could not SET search_path TO ${searchPath}`), client);
+            });
+        });
+    }
+    return {
+        sql: createPgExecutor(pool),
+        open: createPoolOpener(pool, searchPath),
+        end: () => pool.end(),
+    };
+};
+//# sourceMappingURL=pool.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

package/dist/skills/index.d.ts

@@ -64,5 +64,6 @@ export interface SkillResolver {
     }): Promise<SkillVersion>;
 }
 export * from "./catalogue.js";
+export * from "./context.js";
 export * from "./resolver.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/skills/index.js

@@ -28,5 +28,6 @@ export const SKILL_LIMITS = {
     maxLoadedPerRun: 5,
 };
 export * from "./catalogue.js";
+export * from "./context.js";
 export * from "./resolver.js";
 //# sourceMappingURL=index.js.map

package/dist/telemetry/spans.js

@@ -36,6 +36,11 @@ export const SPAN_FOR_RUN_EVENT = {
     "question.answered": "hitl.question",
     "approval.requested": "hitl.approval",
     "approval.decided": "hitl.approval",
+    // Its own span rather than `hitl.approval`: both pause a run for a person, and the questions they answer are
+    // different — "may I do this" versus "I have no access, grant me some" — so a trace that merged them would
+    // make "how often do runs stall on a missing connection" unanswerable.
+    "connection.requested": "hitl.connection",
+    "connection.completed": "hitl.connection",
     "usage.updated": "run.step",
     "context.compacted": "context.compact",
     // Its own span, not `run.step`: a guardrail verdict is the boundary of a decision somebody will need to find

package/dist/testing/conformance/artifact-exports.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `ArtifactExportStore` conformance (#134).
+ *
+ * Almost entirely about `claim`, because that is the method whose contract two adapters can plausibly get
+ * differently and where differing is expensive: a claim that is not exclusive renders the same PDF twice and
+ * leaves two rows pointing at two identical files, and a caller has no way to tell which is canonical.
+ */
+import type { ArtifactId, ConversationId, TenantId } from "../../core/ids.js";
+import type { ArtifactExportStore } from "../../persistence/index.js";
+import { type Fixture, type FixtureOrStore } from "./parents.js";
+/** The parent an adapter with a foreign key needs: an artifact, which itself needs a conversation. */
+export type ExportFixture = Fixture<ArtifactExportStore> & {
+    readonly seedArtifact?: (input: {
+        readonly tenantId: TenantId;
+        readonly artifactId: ArtifactId;
+        readonly conversationId: ConversationId;
+    }) => Promise<void>;
+};
+export declare function artifactExportStoreConformance(make: () => FixtureOrStore<ArtifactExportStore> | Promise<FixtureOrStore<ArtifactExportStore>>): void;
+//# sourceMappingURL=artifact-exports.d.ts.map

package/dist/testing/conformance/artifact-exports.js

@@ -0,0 +1,172 @@
+/**
+ * `ArtifactExportStore` conformance (#134).
+ *
+ * Almost entirely about `claim`, because that is the method whose contract two adapters can plausibly get
+ * differently and where differing is expensive: a claim that is not exclusive renders the same PDF twice and
+ * leaves two rows pointing at two identical files, and a caller has no way to tell which is canonical.
+ */
+import { describe, expect, it } from "vitest";
+import { asId } from "../../core/ids.js";
+import { openFixture } from "./parents.js";
+const T1 = asId("conf-export-tenant-1");
+const T2 = asId("conf-export-tenant-2");
+const A1 = asId("conf-export-artifact-1");
+const AT = "2026-08-23T12:00:00.000Z";
+const USER = asId("conf-export-user");
+const requested = (overrides = {}) => ({
+    id: overrides.id ?? "e1",
+    artifactId: A1,
+    version: overrides.version ?? 1,
+    format: overrides.format ?? "pdf",
+    requestedBy: USER,
+    createdAt: AT,
+});
+export function artifactExportStoreConformance(make) {
+    describe("ArtifactExportStore conformance", () => {
+        const open = async () => {
+            const fixture = openFixture(await make());
+            // Both tenants, because every isolation case below needs the parent to exist on both sides — otherwise
+            // a cross-tenant write would fail on the foreign key and look like isolation working.
+            for (const tenantId of [T1, T2]) {
+                await fixture.seedArtifact?.({
+                    tenantId,
+                    artifactId: A1,
+                    conversationId: asId("conf-export-convo-1"),
+                });
+            }
+            return fixture.store;
+        };
+        it("claims a slot and records it pending", async () => {
+            const store = await open();
+            const result = await store.claim({ tenantId: T1, export: requested() });
+            expect(result.claimed).toBe(true);
+            expect(result.export).toMatchObject({ id: "e1", version: 1, format: "pdf", state: "pending" });
+        });
+        it("lets exactly one of two racing claims win, and hands the loser the winner's row", async () => {
+            // The property the whole port exists for. Both callers then read the same row, which is why the loser
+            // gets it rather than an error: its next move is identical either way.
+            const store = await open();
+            const results = await Promise.all([
+                store.claim({ tenantId: T1, export: requested({ id: "race-a" }) }),
+                store.claim({ tenantId: T1, export: requested({ id: "race-b" }) }),
+            ]);
+            expect(results.filter((r) => r.claimed)).toHaveLength(1);
+            const winner = results.find((r) => r.claimed).export;
+            const loser = results.find((r) => !r.claimed).export;
+            expect(loser.id).toBe(winner.id);
+        });
+        it("treats a different format as a different slot", async () => {
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested({ id: "e1", format: "pdf" }) });
+            const second = await store.claim({ tenantId: T1, export: requested({ id: "e2", format: "markdown" }) });
+            expect(second.claimed).toBe(true);
+        });
+        it("treats a different version as a different slot", async () => {
+            // An export is of a *version*. Sharing one across versions would hand someone last week's document.
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested({ id: "e1", version: 1 }) });
+            const second = await store.claim({ tenantId: T1, export: requested({ id: "e2", version: 2 }) });
+            expect(second.claimed).toBe(true);
+        });
+        it("does not share a slot across tenants", async () => {
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested({ id: "e1" }) });
+            const other = await store.claim({ tenantId: T2, export: requested({ id: "e2" }) });
+            expect(other.claimed).toBe(true);
+            expect(await store.get({ tenantId: T2, id: "e1" })).toBeNull();
+        });
+        it("records a rendered outcome with its file and checksum", async () => {
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested() });
+            expect(await store.complete({
+                tenantId: T1,
+                id: "e1",
+                state: "rendered",
+                fileId: asId("file-1"),
+                byteSize: 2048,
+                checksum: "abc",
+                at: AT,
+            })).toEqual({ recorded: true });
+            expect(await store.get({ tenantId: T1, id: "e1" })).toMatchObject({
+                state: "rendered",
+                fileId: "file-1",
+                byteSize: 2048,
+                checksum: "abc",
+                renderedAt: AT,
+            });
+        });
+        it("records a failure with its reason and message", async () => {
+            // AC-4 depends on both surviving storage: the reason drives behaviour and the message is what the user
+            // reads, so a store keeping one and dropping the other would half-work.
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested() });
+            await store.complete({
+                tenantId: T1,
+                id: "e1",
+                state: "failed",
+                failureReason: "render-failed",
+                failureMessage: "That artifact could not be rendered.",
+                at: AT,
+            });
+            expect(await store.get({ tenantId: T1, id: "e1" })).toMatchObject({
+                state: "failed",
+                failureReason: "render-failed",
+                failureMessage: "That artifact could not be rendered.",
+            });
+        });
+        it("does not complete another tenant's export", async () => {
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested() });
+            // Reported rather than thrown: it is the same answer a deleted row gives, and a worker must be able to
+            // tell "gone" from "broken".
+            expect(await store.complete({ tenantId: T2, id: "e1", state: "rendered", fileId: asId("f"), at: AT })).toEqual({ recorded: false });
+            expect(await store.get({ tenantId: T1, id: "e1" })).toMatchObject({ state: "pending" });
+        });
+        it("finds an export by version and format, which is the cache lookup", async () => {
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested({ id: "e1" }) });
+            expect(await store.find({ tenantId: T1, artifactId: A1, version: 1, format: "pdf" })).toMatchObject({
+                id: "e1",
+            });
+            expect(await store.find({ tenantId: T1, artifactId: A1, version: 1, format: "markdown" })).toBeNull();
+            expect(await store.find({ tenantId: T2, artifactId: A1, version: 1, format: "pdf" })).toBeNull();
+        });
+        it("lists an artifact's exports, paging on a keyset cursor", async () => {
+            // Two formats requested together share a timestamp, so a cursor on the timestamp alone would skip or
+            // repeat -- which is the normal case here rather than a rare one.
+            const store = await open();
+            for (const n of [1, 2, 3, 4, 5]) {
+                await store.claim({
+                    tenantId: T1,
+                    export: { ...requested({ id: `e${n}`, version: n }), createdAt: AT },
+                });
+            }
+            const seen = [];
+            let cursor;
+            do {
+                const page = await store.listByArtifact({
+                    tenantId: T1,
+                    artifactId: A1,
+                    limit: 2,
+                    ...(cursor === undefined ? {} : { cursor }),
+                });
+                seen.push(...page.items.map((e) => e.id));
+                cursor = page.nextCursor;
+            } while (cursor !== undefined);
+            expect(seen.sort()).toEqual(["e1", "e2", "e3", "e4", "e5"]);
+        });
+        it("lists nothing for another tenant", async () => {
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested() });
+            expect((await store.listByArtifact({ tenantId: T2, artifactId: A1, limit: 10 })).items).toEqual([]);
+        });
+        it("rejects a non-timestamp `at` rather than storing it", async () => {
+            // The lesson from #129: a reference adapter laxer than the real one turns a production write failure
+            // into a passing test.
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested() });
+            await expect(store.complete({ tenantId: T1, id: "e1", state: "rendered", fileId: asId("f"), at: "t" })).rejects.toThrow();
+        });
+    });
+}
+//# sourceMappingURL=artifact-exports.js.map

package/dist/testing/conformance/artifacts.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `ArtifactStore` conformance (#133) — AC-6.
+ *
+ * The cases are mostly about **versioning**, because that is the part where two adapters can plausibly
+ * disagree and where disagreeing is expensive: an earlier version that stops resolving is a shared link that
+ * 404s, and a race that silently collapses two regenerations into one is data loss that looks like success.
+ */
+import type { ArtifactStore } from "../../persistence/index.js";
+import { type FixtureOrStore } from "./parents.js";
+export declare function artifactStoreConformance(make: () => FixtureOrStore<ArtifactStore> | Promise<FixtureOrStore<ArtifactStore>>): void;
+//# sourceMappingURL=artifacts.d.ts.map