@retinue/agentkit 0.2.0 → 0.3.1

package/dist/adapters/supabase/rls.js

@@ -72,6 +72,13 @@ export const TENANT_SCOPED_TABLES = [
     { table: "idempotency_keys" },
     { table: "skills" },
     { table: "mcp_connections" },
+    /**
+     * #261. A tenant's third-party credentials, and therefore the table where a missing policy would be worst:
+     * every row is somebody's access to somebody else's system, and the plain `tenant_id` predicate is exactly
+     * the isolation the port already enforces in its `WHERE` clauses. Defence in depth, and #91 is the reminder
+     * that a method accepting a tenant scope and not using it typechecks perfectly.
+     */
+    { table: "connections" },
     { table: "principal_memory", extraPredicate: PRINCIPAL_PREDICATE },
     // `blobs`, not the SPEC's `blob_refs`: BlobStore stores the value, and the metadata-and-pointer
     // design belongs to FileMetadataStore (#129) / ArtifactStore (#133).
@@ -98,6 +105,32 @@ export const TENANT_SCOPED_TABLES = [
      */
     { table: "flow_definitions" },
     { table: "flow_executions" },
+    /**
+     * #271. The knowledge graph, all five tables, and they belong here rather than beside `knowledge_chunks`
+     * in the vector list: none of them needs pgvector, so they exist in every deployment and can be protected
+     * unconditionally.
+     *
+     * Worth stating why the *settings* table needs a policy as much as the content ones. `knowledge_graph_settings`
+     * holds one boolean, so it looks harmless — but it is the switch that decides whether a tenant is paying for
+     * extraction, and a missing policy would let one tenant read, and worse write, another's. Turning a
+     * neighbour's GraphRAG on is a bill they did not agree to.
+     */
+    { table: "knowledge_graph_settings" },
+    { table: "knowledge_graph_sources" },
+    /**
+     * The contributions table is the one to get right. It holds the entities and relationships each source
+     * asserted, as JSON — which is to say, the substance of the documents themselves in condensed form. A leak
+     * here is a leak of what a tenant's corpus says, not merely of which entities exist.
+     */
+    { table: "knowledge_graph_contributions" },
+    { table: "knowledge_graph_entities" },
+    { table: "knowledge_graph_relationships" },
+    /**
+     * #272. Community summaries are **generated prose about a tenant's corpus** — a paraphrase of what their
+     * documents say, which is if anything more sensitive than the entity names next door. A missing policy here
+     * would leak the substance of a corpus rather than its index.
+     */
+    { table: "knowledge_graph_communities" },
 ];
 /**
  * Tables that deliberately have no tenant policy, each with the reason.

package/dist/agents/agent.d.ts

@@ -15,13 +15,52 @@ import { type ProviderCredentials } from "../models/provider-factory.js";
 import type { ModelProvider } from "../models/index.js";
 import type { AuthorizationPolicy } from "../authorization/index.js";
 import { type ContextProvider } from "../context/index.js";
-import { type ToolProvider, type ToolSearch, type ToolsetResolver } from "../tools/index.js";
+import { type ShadowRecorder, type ToolProvider, type ToolSearch, type ToolsetResolver } from "../tools/index.js";
 import type { TokenBudget } from "../core/budget.js";
 import { type AgentEngine, type ProcessOutcome } from "../runtime/index.js";
 import type { Guardrail } from "../guardrails/index.js";
+import { type SkillResolver } from "../skills/index.js";
 import { type ResolvedModelInfo } from "./engine.js";
 import type { AgentManifest } from "./index.js";
 import { type AgentManifestInput } from "./define.js";
+/**
+ * The policy this agent runs under — task #244, the interpreter for `authorizationPolicyId`.
+ *
+ * The field was declared and read by nothing, so an agent naming `"restricted"` ran under whatever the host had
+ * wired — very possibly the permissive default. Three rules, and the third is the one that matters:
+ *
+ * 1. A map is supplied and contains the id → that policy.
+ * 2. No map, and the id is `defineAgent`'s `"default"` → the single wired policy, or the permissive default.
+ *    This is the normal case and stays a one-liner.
+ * 3. **Any other combination is an error.** An id the deployment cannot honour must never fall through to the
+ *    permissive default: an agent asking to run under a narrow policy and silently getting allow-all is the
+ *    worst possible reading of this field, and it is the reading it had. Failing at construction is loud, early
+ *    and cheap.
+ *
+ * Note the platform does not check that a named policy is *narrower* than any other. It cannot: a policy is an
+ * interface the host implements, and composing two of them into an intersection would mean second-guessing a
+ * deployment's own authorization. What the platform guarantees is that the policy an agent named is the policy
+ * it got, or the run does not start.
+ */
+export declare const selectAuthorization: (config: Pick<CreateAgentConfig, "authorization" | "authorizationPolicies">, manifest: Pick<AgentManifest, "authorizationPolicyId" | "id">) => AuthorizationPolicy;
+/**
+ * The providers this agent asked for, in the order it asked — task #244.
+ *
+ * `AgentManifest.contextProviderIds` was declared and read by nothing, so a manifest naming two of four wired
+ * providers got all four, and naming none got all of them too. Two decisions make the field meaningful without
+ * making it a trap:
+ *
+ * - **An empty list means every wired provider**, not none. `defineAgent` defaults it to `[]`, so treating empty
+ *   as "no context" would silently strip the memory, notes and attachments from every agent already written
+ *   against the default. The field is a *selection*, and no selection means no narrowing.
+ * - **A named id that is not wired is an error**, not a silent omission. The failure it prevents is the one worth
+ *   preventing: an agent whose manifest asks for `principal-memory`, a typo or a missing wire, and an assistant
+ *   that quietly remembers nothing. That reads exactly like a model that chose not to use its memory.
+ *
+ * Order follows the manifest, because section order is prompt order and the manifest is where an author can see
+ * and control it.
+ */
+export declare const selectContextProviders: (wired: readonly ContextProvider[], manifest: Pick<AgentManifest, "contextProviderIds" | "id">) => readonly ContextProvider[];
 export type CreateAgentConfig = {
     readonly manifest: AgentManifestInput;
     /** Model catalog; defaults to a small Anthropic catalog (smart/fast). */
@@ -40,6 +79,15 @@ export type CreateAgentConfig = {
      */
     readonly randomHex?: (bytes: number) => string;
     readonly authorization?: AuthorizationPolicy;
+    /**
+     * Named policies a manifest may select with `authorizationPolicyId` — task #244.
+     *
+     * Absent is the normal case: one `authorization` (or the permissive default), and every manifest carrying
+     * `defineAgent`'s `"default"`. Supplying a map is how a deployment runs several agents under different
+     * policies — a customer-facing agent under a narrow one, an internal agent under a wider one — without the
+     * host having to build a separate registry per agent.
+     */
+    readonly authorizationPolicies?: Readonly<Record<string, AuthorizationPolicy>>;
     /**
      * Checks to run before the model sees a turn and before anything leaves it — REQ-046 (#205), AC-5.
      *
@@ -59,7 +107,24 @@ export type CreateAgentConfig = {
     readonly catalogBudget?: TokenBudget;
     /** A tenant's category switches, applied before authorization — task #210, AC-4. */
     readonly toolsets?: ToolsetResolver;
+    /**
+     * A skill resolver — task #244, and what makes `manifest.skillPolicy` mean something.
+     *
+     * Wiring is the toggle, the rule `toolSearch` already follows. Supplying one adds a skills catalogue section
+     * to the prompt (names and descriptions, filtered by the manifest's `assigned`/`allowTenantSkills`) and makes
+     * `load_skill` real; omitting it means neither is advertised.
+     */
+    readonly skills?: SkillResolver;
     readonly tenantId?: string;
+    /**
+     * Where a shadow run's suppressed writes go — required to run one at all.
+     *
+     * Without it `createAgent` cannot run a shadow turn: the registry refuses a gated tool when
+     * `context.shadow` is true and no recorder is configured, which is the correct fail-closed rule but meant
+     * this runner had no way to satisfy it. Parity measurement needs a run driven to completion in one process,
+     * and this is that seam.
+     */
+    readonly shadow?: ShadowRecorder;
     /** Test/advanced seam: override how a manifest resolves to a model (e.g. a mock model). */
     readonly resolveModel?: (manifest: AgentManifest, context: ExecutionContext) => ResolvedModelInfo;
     /** Test/advanced seam: supply the engine directly instead of building the default one. */
@@ -71,6 +136,18 @@ export type RunInput = {
     readonly message: string;
     readonly principalId?: string;
     readonly roleIds?: readonly string[];
+    /**
+     * Run with every gated effect suppressed and recorded instead of performed.
+     *
+     * Per-run rather than per-agent, because the same agent serves both: a parity harness shadows one turn and
+     * runs the next for real. `shadow` without `config.shadow` is refused by the registry rather than performed
+     * — announcing a shadow run with nowhere to record it is not a licence to publish.
+     *
+     * Note what shadow mode does **not** suppress: an `internal-write` still happens, so a shadow run really
+     * does create drafts. It measures everything up to the external write and nothing after it, because what an
+     * agent does after publishing cannot be observed without publishing.
+     */
+    readonly shadow?: boolean;
 };
 export type RunResult = {
     readonly runId: string;

package/dist/agents/agent.js

@@ -17,14 +17,95 @@ import { createProviderFactory, } from "../models/provider-factory.js";
 import { gatherSections } from "../context/index.js";
 import { randomBytes } from "node:crypto";
 import { makeNonce, renderContextBlock } from "../security/prompt-safety.js";
-import { createToolRegistry } from "../tools/index.js";
+import { createToolRegistry, } from "../tools/index.js";
 import { createDurableWorker } from "../runtime/index.js";
 import { createMemoryCheckpointStore, createMemoryRunEventLog, createMemoryRunStore, } from "../adapters/memory/runtime.js";
 import { createMemoryConversationStore } from "../adapters/memory/index.js";
 import { createMemoryEventBus } from "../runtime/index.js";
 import { createMemoryMessageStore } from "../adapters/memory/message-store.js";
+import { createSkillBodyLoader, createSkillCatalogueProvider, } from "../skills/index.js";
 import { createDefaultEngine } from "./engine.js";
 import { DEFAULT_MODEL_CATALOG, DEFAULT_ROLE_ASSIGNMENTS, defineAgent, } from "./define.js";
+/**
+ * The policy this agent runs under — task #244, the interpreter for `authorizationPolicyId`.
+ *
+ * The field was declared and read by nothing, so an agent naming `"restricted"` ran under whatever the host had
+ * wired — very possibly the permissive default. Three rules, and the third is the one that matters:
+ *
+ * 1. A map is supplied and contains the id → that policy.
+ * 2. No map, and the id is `defineAgent`'s `"default"` → the single wired policy, or the permissive default.
+ *    This is the normal case and stays a one-liner.
+ * 3. **Any other combination is an error.** An id the deployment cannot honour must never fall through to the
+ *    permissive default: an agent asking to run under a narrow policy and silently getting allow-all is the
+ *    worst possible reading of this field, and it is the reading it had. Failing at construction is loud, early
+ *    and cheap.
+ *
+ * Note the platform does not check that a named policy is *narrower* than any other. It cannot: a policy is an
+ * interface the host implements, and composing two of them into an intersection would mean second-guessing a
+ * deployment's own authorization. What the platform guarantees is that the policy an agent named is the policy
+ * it got, or the run does not start.
+ */
+export const selectAuthorization = (config, manifest) => {
+    const id = manifest.authorizationPolicyId ?? "default";
+    const named = config.authorizationPolicies;
+    if (named !== undefined) {
+        const chosen = named[id];
+        if (chosen !== undefined)
+            return chosen;
+        throw new AgentPlatformError({
+            code: "capability_unavailable",
+            message: `agent "${manifest.id}" runs under authorization policy "${id}" and no such policy is registered ` +
+                `(registered: ${Object.keys(named).map((k) => `"${k}"`).join(", ") || "none"}). Refusing rather than ` +
+                "falling back — an agent that asked for a narrow policy and silently got a permissive one is the " +
+                "failure this field exists to prevent.",
+            retryable: false,
+        });
+    }
+    if (id !== "default")
+        throw new AgentPlatformError({
+            code: "capability_unavailable",
+            message: `agent "${manifest.id}" runs under authorization policy "${id}" and none is registered. Pass ` +
+                "`authorizationPolicies: { \"" +
+                id +
+                "\": … }`, or leave the manifest's `authorizationPolicyId` at \"default\".",
+            retryable: false,
+        });
+    return config.authorization ?? allowAllAuthorization();
+};
+/**
+ * The providers this agent asked for, in the order it asked — task #244.
+ *
+ * `AgentManifest.contextProviderIds` was declared and read by nothing, so a manifest naming two of four wired
+ * providers got all four, and naming none got all of them too. Two decisions make the field meaningful without
+ * making it a trap:
+ *
+ * - **An empty list means every wired provider**, not none. `defineAgent` defaults it to `[]`, so treating empty
+ *   as "no context" would silently strip the memory, notes and attachments from every agent already written
+ *   against the default. The field is a *selection*, and no selection means no narrowing.
+ * - **A named id that is not wired is an error**, not a silent omission. The failure it prevents is the one worth
+ *   preventing: an agent whose manifest asks for `principal-memory`, a typo or a missing wire, and an assistant
+ *   that quietly remembers nothing. That reads exactly like a model that chose not to use its memory.
+ *
+ * Order follows the manifest, because section order is prompt order and the manifest is where an author can see
+ * and control it.
+ */
+export const selectContextProviders = (wired, manifest) => {
+    const asked = manifest.contextProviderIds ?? [];
+    if (asked.length === 0)
+        return wired;
+    const byId = new Map(wired.map((p) => [p.id, p]));
+    const missing = asked.filter((id) => !byId.has(id));
+    if (missing.length > 0)
+        throw new AgentPlatformError({
+            code: "capability_unavailable",
+            message: `agent "${manifest.id}" asks for context provider(s) ${missing.map((m) => `"${m}"`).join(", ")} and ` +
+                `nothing wired supplies them (wired: ${wired.map((p) => `"${p.id}"`).join(", ") || "none"}). An agent ` +
+                "that silently runs without the context it declared is indistinguishable from a model choosing not to " +
+                "use it.",
+            retryable: false,
+        });
+    return asked.map((id) => byId.get(id));
+};
 /** Permissive policy used by the embedded facade when a caller wires tools but no authorization. */
 const allowAllAuthorization = () => ({
     async can() {
@@ -55,13 +136,27 @@ export const createAgent = (config) => {
         roles: config.roleAssignments ?? DEFAULT_ROLE_ASSIGNMENTS,
     });
     const providerFactory = createProviderFactory({ credentials: config.providerCredentials ?? {} });
-    const authorization = config.authorization ?? allowAllAuthorization();
+    const authorization = selectAuthorization(config, manifest);
+    /**
+     * Skills, when a resolver is wired — #244.
+     *
+     * Both halves read the *same* policy, and that is the point: `createSkillBodyLoader` re-derives the catalogue
+     * before loading, so `assigned` and `allowTenantSkills` gate loading as well as listing. A policy that
+     * filtered the list but not the load would be no policy at all — a model that guessed a name would get it.
+     */
+    const skillPolicy = {
+        assigned: manifest.skillPolicy?.assigned ?? [],
+        allowTenantSkills: manifest.skillPolicy?.allowTenantSkills ?? false,
+    };
+    const skillLoader = config.skills === undefined ? undefined : createSkillBodyLoader({ resolver: config.skills, policy: skillPolicy });
     const toolRegistry = createToolRegistry({
         providers: config.tools ?? [],
         authorization,
         ...(config.toolSearch === undefined ? {} : { search: config.toolSearch }),
         ...(config.toolsets === undefined ? {} : { toolsets: config.toolsets }),
         ...(config.catalogBudget === undefined ? {} : { catalogBudget: config.catalogBudget }),
+        ...(skillLoader === undefined ? {} : { skills: skillLoader }),
+        ...(config.shadow === undefined ? {} : { shadow: config.shadow }),
     });
     const resolveModel = config.resolveModel ??
         ((m) => {
@@ -70,10 +165,22 @@ export const createAgent = (config) => {
                 model: providerFactory.languageModel(def),
                 modelId: def.modelId,
                 currency: def.pricing.currency,
-                price: (u) => computeModelCostMinorUnits(def.pricing, { inputTokens: u.inputTokens, outputTokens: u.outputTokens, cachedInputTokens: u.cachedInputTokens }),
+                price: (u) => computeModelCostMinorUnits(def.pricing, {
+                    inputTokens: u.inputTokens,
+                    outputTokens: u.outputTokens,
+                    cachedInputTokens: u.cachedInputTokens,
+                    // Dropped here before #247, so a cache write was billed as fresh input — and on a provider that
+                    // charges a premium for a write, under-billed.
+                    ...(u.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: u.cacheWriteTokens }),
+                }),
             };
         });
-    const contextProviders = config.contextProviders ?? [];
+    const contextProviders = [
+        ...(config.contextProviders ?? []),
+        ...(config.skills === undefined
+            ? []
+            : [createSkillCatalogueProvider({ resolver: config.skills, policy: skillPolicy })]),
+    ];
     const engine = config.engine ?? createDefaultEngine({
         ...(config.guardrails === undefined ? {} : { guardrails: config.guardrails }),
         ...(config.catalogBudget === undefined ? {} : { catalogBudget: config.catalogBudget }),
@@ -96,7 +203,7 @@ export const createAgent = (config) => {
                  * assembly, so content cannot learn the delimiter from a previous turn.
                  */
                 systemPrompt: async (m, context) => {
-                    const sections = await gatherSections(context, contextProviders);
+                    const sections = await gatherSections(context, selectContextProviders(contextProviders, m));
                     if (sections.length === 0)
                         return m.instructions;
                     const ctxText = renderContextBlock(sections, makeNonce(config.randomHex ?? defaultRandomHex));
@@ -141,6 +248,9 @@ export const createAgent = (config) => {
                     const resolvedTools = descriptors.map((descriptor) => ({
                         name: descriptor.name,
                         description: descriptor.description,
+                        // Carried through so the engine can honour `toolPolicy.categories` without reaching back into
+                        // the registry for a descriptor it already handed over — #244.
+                        category: descriptor.category,
                         inputSchema: descriptor.inputSchema,
                         execute: async (input) => {
                             const result = await toolRegistry.execute(context, { name: descriptor.name, input });
@@ -259,6 +369,9 @@ export const createAgent = (config) => {
                 requestId: asId(`req-${seq}`),
                 conversationId,
                 runId,
+                // Only when asked. Defaulting to shadow would make every existing run a shadow run; the dangerous
+                // direction — claiming shadow with nowhere to record it — is closed in the registry instead.
+                ...(input.shadow === true ? { shadow: true } : {}),
             };
             contextByRun.set(runId, context);
             if (!(await conversations.findById({ tenantId, id: conversationId }))) {

package/dist/agents/define.js

@@ -39,9 +39,22 @@ export const DEFAULT_MODEL_CATALOG = [
         label: "Claude Sonnet 5",
         lifecycle: "generally-available",
         inputModalities: ["text", "image"],
-        capabilities: { tools: true, structuredOutput: true, reasoning: true, nativeSearch: false },
+        capabilities: { tools: true, structuredOutput: true, reasoning: true, nativeSearch: false, promptCaching: "explicit" },
         limits: { contextTokens: 200_000, maxOutputTokens: 8_192 },
-        pricing: { currency: "USD", inputPerMillion: 3_000, outputPerMillion: 15_000 },
+        /**
+         * Cache rates, added by #247.
+         *
+         * Anthropic's published ratios: a cache **read** is 0.1× a fresh input token and a cache **write** is
+         * **1.25×** — a write costs *more*. `cacheWritePerMillion` was in `ModelPricing` and read by nothing, so a
+         * cache write was billed as ordinary input and the first turn of every conversation was under-billed.
+         */
+        pricing: {
+            currency: "USD",
+            inputPerMillion: 3_000,
+            outputPerMillion: 15_000,
+            cacheReadPerMillion: 300,
+            cacheWritePerMillion: 3_750,
+        },
         dataResidency: ["us"],
     },
     {
@@ -50,9 +63,16 @@ export const DEFAULT_MODEL_CATALOG = [
         label: "Claude Haiku 4.5",
         lifecycle: "generally-available",
         inputModalities: ["text", "image"],
-        capabilities: { tools: true, structuredOutput: true, reasoning: false, nativeSearch: false },
+        capabilities: { tools: true, structuredOutput: true, reasoning: false, nativeSearch: false, promptCaching: "explicit" },
         limits: { contextTokens: 200_000, maxOutputTokens: 8_192 },
-        pricing: { currency: "USD", inputPerMillion: 800, outputPerMillion: 4_000 },
+        pricing: {
+            currency: "USD",
+            inputPerMillion: 800,
+            outputPerMillion: 4_000,
+            // Same ratios as Sonnet above: read 0.1×, write 1.25×.
+            cacheReadPerMillion: 80,
+            cacheWritePerMillion: 1_000,
+        },
         dataResidency: ["us"],
     },
 ];

package/dist/agents/engine.d.ts

@@ -18,6 +18,7 @@
  *    on a refusal the model cannot resolve.
  */
 import type { ExecutionContext } from "../core/context.js";
+import { type ConnectionNeed } from "../connections/pause.js";
 import type { RunId, TenantId } from "../core/ids.js";
 import type { ModelDefinition, ModelTurnRequest, ModelTurnTool, NeutralStreamChunk, NeutralUsage, ResolvedModel, TurnMessage } from "../models/index.js";
 import { type Guardrail } from "../guardrails/index.js";
@@ -121,6 +122,25 @@ export type DefaultEngineDeps = {
     readonly now?: () => number;
     /** The streaming primitive. Defaults to the models-layer `streamModelTurn`; overridden in tests. */
     readonly streamTurn?: (req: ModelTurnRequest) => AsyncIterable<NeutralStreamChunk>;
+    /**
+     * Turns "this run needs a connection" into somewhere to send a person — task #264.
+     *
+     * **Optional, and its absence means today's behaviour**: the tool call fails and the run fails with it. That
+     * is the correct default, not a degraded one — a host with no OAuth flow wired has no login URL to offer, and
+     * pausing a run for a consent screen nobody can reach would hang it for ever.
+     *
+     * Returning `null` says the same thing for one provider: this one is token-only, so fail rather than pause.
+     * That decision comes from `ToolkitAuth.modes`, which is why #260 kept `AuthMode` separate from
+     * `CredentialScheme` — an OAuth token is presented as a bearer, so the wire format cannot answer it.
+     */
+    readonly connectionConsent?: (input: {
+        readonly context: ExecutionContext;
+        readonly need: ConnectionNeed;
+    }) => Promise<{
+        readonly loginUrl: string;
+        readonly scopes: readonly string[];
+        readonly expiresAt: string;
+    } | null>;
 };
 export declare const createDefaultEngine: (deps: DefaultEngineDeps) => AgentEngine;
 //# sourceMappingURL=engine.d.ts.map