@retinue/agentkit 0.1.0

package/dist/artifacts/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The artifact lifecycle — `docs/05-knowledge-and-documents.md`, REQ-028 (#133).
+ *
+ * The store holds rows; what lives here is the part no store can hold: **entitlement**, and the pairing of a
+ * version row with the content it references.
+ *
+ * - **AC-4 is enforced, not asserted.** `AuthorizationPolicy` is a required dependency and the decision is
+ *   about the *conversation*, so an artifact is never more accessible than the conversation that produced it
+ *   and there is no second permission model to keep in step with the first. The same shape #129 settled on
+ *   for files, deliberately: two different answers to "who may read this" is one too many.
+ * - **A version and its content are written in one call**, in the order that makes a crash survivable: blob
+ *   first, row second. The reverse leaves a row pointing at content that does not exist, and a dangling
+ *   reference reads as corruption while an unreferenced blob is merely waste.
+ */
+import type { ExecutionContext, Page } from "../core/context.js";
+import type { ArtifactId, ConversationId } from "../core/ids.js";
+import type { AuthorizationPolicy } from "../authorization/index.js";
+import type { Artifact, ArtifactKind, ArtifactProvenance, ArtifactStore, ArtifactVersion, BlobStore } from "../persistence/index.js";
+/**
+ * The largest artifact this platform will store.
+ *
+ * A ceiling exists because an artifact is model output and model output has no natural bound. 4 MiB is a very
+ * long report and far past anything a context window produced in one turn — so in practice it catches a loop
+ * writing the same paragraph a thousand times, which is what it is for.
+ */
+export declare const MAX_ARTIFACT_BYTES: number;
+export type ArtifactContent = {
+    readonly kind: ArtifactKind;
+    /** The content itself. Markdown and structured content are both strings or JSON values. */
+    readonly value: unknown;
+};
+export type ArtifactServiceDeps = {
+    readonly artifacts: ArtifactStore;
+    readonly blobs: BlobStore;
+    /**
+     * AC-4, enforced rather than asserted.
+     *
+     * **Required.** A service that would run without a policy is a service someone constructs without one, and
+     * at that point every artifact in the tenant is readable by every member of it. Tenant scoping is not AC-4.
+     */
+    readonly authorization: AuthorizationPolicy;
+    readonly clock?: () => string;
+    readonly artifactId?: () => string;
+    readonly versionId?: () => string;
+};
+/**
+ * The size of a content value once stored.
+ *
+ * Measured on the serialised form, because that is what is stored and what is billed. Measuring the string
+ * before serialisation would under-count a structured value by exactly the amount its encoding adds.
+ */
+export declare const contentByteSize: (value: unknown) => number;
+export declare const createArtifactService: (deps: ArtifactServiceDeps) => {
+    /** Create an artifact at version 1. */
+    create(context: ExecutionContext, input: {
+        readonly conversationId: ConversationId;
+        readonly name: string;
+        readonly content: ArtifactContent;
+        readonly provenance: ArtifactProvenance;
+    }): Promise<Artifact>;
+    /**
+     * Regenerate: a new version, never an overwrite — AC-2.
+     *
+     * `expectedLatestVersion` is read here rather than taken from the caller, and then passed through as the
+     * compare. That is not redundant: the read establishes what the caller is regenerating *from*, and the
+     * compare makes a concurrent regeneration lose loudly instead of silently replacing this one.
+     */
+    regenerate(context: ExecutionContext, input: {
+        readonly id: ArtifactId;
+        readonly content: ArtifactContent;
+        readonly provenance: ArtifactProvenance;
+    }): Promise<{
+        readonly version: number;
+    }>;
+    /** A version's row and its content together. The latest when no version is asked for. */
+    read(context: ExecutionContext, input: {
+        readonly id: ArtifactId;
+        readonly version?: number;
+    }): Promise<{
+        readonly artifact: Artifact;
+        readonly version: ArtifactVersion;
+        readonly content: unknown;
+    }>;
+    /** The version history, for a restore or an audit. Metadata only — no content is loaded. */
+    history(context: ExecutionContext, input: {
+        readonly id: ArtifactId;
+        readonly limit: number;
+        readonly cursor?: string;
+    }): Promise<Page<ArtifactVersion>>;
+    /**
+     * Restore an earlier version by making it the newest one.
+     *
+     * A *new* version whose content is the old one's, not a pointer moved backwards. Moving a pointer would
+     * make the history lie about what happened — and "the version that was current on Tuesday" is exactly the
+     * question a shared link asks.
+     */
+    restore(context: ExecutionContext, input: {
+        readonly id: ArtifactId;
+        readonly version: number;
+        readonly producedBy?: string;
+    }): Promise<{
+        readonly version: number;
+    }>;
+    listForConversation(context: ExecutionContext, input: {
+        readonly conversationId: ConversationId;
+        readonly limit: number;
+        readonly cursor?: string;
+    }): Promise<Page<Artifact>>;
+    softDelete(context: ExecutionContext, id: ArtifactId): Promise<{
+        readonly deleted: boolean;
+    }>;
+};
+export type ArtifactService = ReturnType<typeof createArtifactService>;
+//# sourceMappingURL=index.d.ts.map

package/dist/artifacts/index.js

@@ -0,0 +1,219 @@
+/**
+ * The artifact lifecycle — `docs/05-knowledge-and-documents.md`, REQ-028 (#133).
+ *
+ * The store holds rows; what lives here is the part no store can hold: **entitlement**, and the pairing of a
+ * version row with the content it references.
+ *
+ * - **AC-4 is enforced, not asserted.** `AuthorizationPolicy` is a required dependency and the decision is
+ *   about the *conversation*, so an artifact is never more accessible than the conversation that produced it
+ *   and there is no second permission model to keep in step with the first. The same shape #129 settled on
+ *   for files, deliberately: two different answers to "who may read this" is one too many.
+ * - **A version and its content are written in one call**, in the order that makes a crash survivable: blob
+ *   first, row second. The reverse leaves a row pointing at content that does not exist, and a dangling
+ *   reference reads as corruption while an unreferenced blob is merely waste.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { asId } from "../core/ids.js";
+/**
+ * The largest artifact this platform will store.
+ *
+ * A ceiling exists because an artifact is model output and model output has no natural bound. 4 MiB is a very
+ * long report and far past anything a context window produced in one turn — so in practice it catches a loop
+ * writing the same paragraph a thousand times, which is what it is for.
+ */
+export const MAX_ARTIFACT_BYTES = 4 * 1024 * 1024;
+const refuse = (code, message) => new AgentPlatformError({ code, message, retryable: false });
+/**
+ * The size of a content value once stored.
+ *
+ * Measured on the serialised form, because that is what is stored and what is billed. Measuring the string
+ * before serialisation would under-count a structured value by exactly the amount its encoding adds.
+ */
+export const contentByteSize = (value) => new TextEncoder().encode(typeof value === "string" ? value : JSON.stringify(value)).byteLength;
+/** Hex SHA-256 of the stored form, so a read-back can be checked rather than assumed. */
+const checksumOf = async (value) => {
+    const bytes = new TextEncoder().encode(typeof value === "string" ? value : JSON.stringify(value));
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+};
+export const createArtifactService = (deps) => {
+    const clock = deps.clock ?? (() => new Date().toISOString());
+    const newArtifactId = deps.artifactId ?? (() => `art_${crypto.randomUUID()}`);
+    const newVersionId = deps.versionId ?? (() => `ver_${crypto.randomUUID()}`);
+    const authorise = async (context, action, conversationId, absent) => {
+        const decision = await deps.authorization.can(context, action, {
+            type: "conversation",
+            id: conversationId,
+        });
+        // `not_found`, never `forbidden`: a distinct answer here confirms the artifact exists to precisely the
+        // caller who must not learn that.
+        if (!decision.allow)
+            throw refuse("not_found", absent);
+    };
+    const store = async (context, content) => {
+        const byteSize = contentByteSize(content.value);
+        if (byteSize > MAX_ARTIFACT_BYTES)
+            // The limit named, because "too large" sends someone to guess.
+            throw refuse("invalid_input", `that artifact is ${byteSize} bytes and the limit is ${MAX_ARTIFACT_BYTES} bytes`);
+        const checksum = await checksumOf(content.value);
+        // Blob first. A crash here leaves an unreferenced blob, which is waste; the reverse leaves a row pointing
+        // at nothing, which reads as corruption.
+        const ref = await deps.blobs.put({ tenantId: context.tenantId, value: content.value });
+        return { ref, byteSize, checksum };
+    };
+    return {
+        /** Create an artifact at version 1. */
+        async create(context, input) {
+            await authorise(context, "write", input.conversationId, "no such conversation");
+            const { ref, byteSize, checksum } = await store(context, input.content);
+            return deps.artifacts.create({
+                tenantId: context.tenantId,
+                artifact: {
+                    id: asId(newArtifactId()),
+                    conversationId: input.conversationId,
+                    kind: input.content.kind,
+                    name: input.name,
+                    createdAt: clock(),
+                },
+                version: {
+                    id: asId(newVersionId()),
+                    contentRef: ref,
+                    byteSize,
+                    checksum,
+                    provenance: input.provenance,
+                    createdBy: context.principalId,
+                    createdAt: clock(),
+                },
+            });
+        },
+        /**
+         * Regenerate: a new version, never an overwrite — AC-2.
+         *
+         * `expectedLatestVersion` is read here rather than taken from the caller, and then passed through as the
+         * compare. That is not redundant: the read establishes what the caller is regenerating *from*, and the
+         * compare makes a concurrent regeneration lose loudly instead of silently replacing this one.
+         */
+        async regenerate(context, input) {
+            const artifact = await deps.artifacts.get({ tenantId: context.tenantId, id: input.id });
+            if (artifact === null || artifact.deletedAt !== undefined)
+                throw refuse("not_found", "no such artifact");
+            await authorise(context, "write", artifact.conversationId, "no such artifact");
+            const { ref, byteSize, checksum } = await store(context, input.content);
+            const result = await deps.artifacts.addVersion({
+                tenantId: context.tenantId,
+                id: input.id,
+                expectedLatestVersion: artifact.latestVersion,
+                version: {
+                    id: asId(newVersionId()),
+                    contentRef: ref,
+                    byteSize,
+                    checksum,
+                    provenance: input.provenance,
+                    createdBy: context.principalId,
+                    createdAt: clock(),
+                },
+            });
+            if (!result.added || result.version === undefined)
+                // Lost the race, or the artifact was deleted between the read and the write. The blob written above is
+                // now unreferenced — waste, and deliberately not cleaned up here: deleting it would risk removing
+                // content the *winning* version happens to reference if two regenerations produced identical output.
+                throw refuse("conflict", "that artifact changed while this version was being written");
+            return { version: result.version };
+        },
+        /** A version's row and its content together. The latest when no version is asked for. */
+        async read(context, input) {
+            const artifact = await deps.artifacts.get({ tenantId: context.tenantId, id: input.id });
+            if (artifact === null || artifact.deletedAt !== undefined)
+                throw refuse("not_found", "no such artifact");
+            await authorise(context, "read", artifact.conversationId, "no such artifact");
+            const version = await deps.artifacts.getVersion({
+                tenantId: context.tenantId,
+                id: input.id,
+                ...(input.version === undefined ? {} : { version: input.version }),
+            });
+            if (version === null)
+                throw refuse("not_found", "no such version of that artifact");
+            const content = await deps.blobs.get({ tenantId: context.tenantId, ref: version.contentRef });
+            if (content === null)
+                // The row says the content is there and it is not. Reported as what it is rather than as an empty
+                // artifact, because an empty artifact is something a caller might reasonably export.
+                throw refuse("not_found", "that artifact version's content is missing");
+            return { artifact, version, content };
+        },
+        /** The version history, for a restore or an audit. Metadata only — no content is loaded. */
+        async history(context, input) {
+            const artifact = await deps.artifacts.get({ tenantId: context.tenantId, id: input.id });
+            if (artifact === null || artifact.deletedAt !== undefined)
+                throw refuse("not_found", "no such artifact");
+            await authorise(context, "read", artifact.conversationId, "no such artifact");
+            return deps.artifacts.listVersions({
+                tenantId: context.tenantId,
+                id: input.id,
+                limit: input.limit,
+                ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+            });
+        },
+        /**
+         * Restore an earlier version by making it the newest one.
+         *
+         * A *new* version whose content is the old one's, not a pointer moved backwards. Moving a pointer would
+         * make the history lie about what happened — and "the version that was current on Tuesday" is exactly the
+         * question a shared link asks.
+         */
+        async restore(context, input) {
+            const artifact = await deps.artifacts.get({ tenantId: context.tenantId, id: input.id });
+            if (artifact === null || artifact.deletedAt !== undefined)
+                throw refuse("not_found", "no such artifact");
+            await authorise(context, "write", artifact.conversationId, "no such artifact");
+            const source = await deps.artifacts.getVersion({
+                tenantId: context.tenantId,
+                id: input.id,
+                version: input.version,
+            });
+            if (source === null)
+                throw refuse("not_found", "no such version of that artifact");
+            const result = await deps.artifacts.addVersion({
+                tenantId: context.tenantId,
+                id: input.id,
+                expectedLatestVersion: artifact.latestVersion,
+                version: {
+                    id: asId(newVersionId()),
+                    // The *same* blob reference. Copying the content would double the storage for a byte-identical
+                    // value, and a blob is immutable so sharing it is safe.
+                    contentRef: source.contentRef,
+                    byteSize: source.byteSize,
+                    ...(source.checksum === undefined ? {} : { checksum: source.checksum }),
+                    provenance: {
+                        producedBy: input.producedBy ?? "restore",
+                        // The restore records what it restored *from*, so the history explains itself without a reader
+                        // having to compare content refs.
+                        inputs: { restoredFromVersion: input.version },
+                        ...(source.provenance.runId === undefined ? {} : { runId: source.provenance.runId }),
+                        ...(source.provenance.sourceFileIds === undefined
+                            ? {}
+                            : { sourceFileIds: source.provenance.sourceFileIds }),
+                    },
+                    createdBy: context.principalId,
+                    createdAt: clock(),
+                },
+            });
+            if (!result.added || result.version === undefined)
+                throw refuse("conflict", "that artifact changed while the restore was being written");
+            return { version: result.version };
+        },
+        async listForConversation(context, input) {
+            // Authorised before the query runs, not filtered after: for an unentitled caller a page count or a
+            // timing difference still answers "does this conversation have artifacts".
+            await authorise(context, "read", input.conversationId, "no such conversation");
+            return deps.artifacts.listByConversation({ tenantId: context.tenantId, ...input });
+        },
+        async softDelete(context, id) {
+            const artifact = await deps.artifacts.get({ tenantId: context.tenantId, id });
+            if (artifact === null)
+                throw refuse("not_found", "no such artifact");
+            await authorise(context, "write", artifact.conversationId, "no such artifact");
+            return deps.artifacts.softDelete({ tenantId: context.tenantId, id, at: clock() });
+        },
+    };
+};
+//# sourceMappingURL=index.js.map

package/dist/authorization/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Authorization port — `docs/11-authorization.md`. **Frozen v1.**
+ *
+ * A first-class port, not scattered `if` checks. The engine lands in REQ-004; this is the shape
+ * every store, tool and retrieval path takes decisions from. Imports only core + tool contracts —
+ * never an adapter.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { ToolDescriptor } from "../tools/index.js";
+export type ResourceRef = {
+    readonly type: string;
+    readonly id?: string;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+};
+export type Obligation = {
+    readonly kind: "requires-approval";
+    readonly riskCategory?: string;
+} | {
+    readonly kind: "redact";
+    readonly fields: readonly string[];
+};
+export type Decision = {
+    readonly allow: boolean;
+    readonly reason?: string;
+    readonly obligations?: readonly Obligation[];
+};
+/** The query-time filter applied *before* search, so retrieval never returns unauthorized rows. */
+export type PermissionScope = {
+    readonly tenantId: string;
+    readonly roleIds: readonly string[];
+    readonly filter?: Readonly<Record<string, unknown>>;
+};
+export interface AuthorizationPolicy {
+    /** A single point decision; may carry obligations (e.g. requires-approval, redact). */
+    can(context: ExecutionContext, action: string, resource: ResourceRef): Promise<Decision>;
+    /** The permission-filtered catalog, computed before discovery. */
+    filterTools(context: ExecutionContext, tools: readonly ToolDescriptor[]): Promise<readonly ToolDescriptor[]>;
+    /** The scope filter for a resource type, applied before any list/search. */
+    scope(context: ExecutionContext, resourceType: string): Promise<PermissionScope>;
+}
+export type Permission = {
+    /** e.g. "read" | "execute" | "publish" | "*" */
+    readonly action: string;
+    /** e.g. "conversation" | "tool" | "*" */
+    readonly resourceType: string;
+    /** When true, a granted decision carries a requires-approval obligation. */
+    readonly requiresApproval?: boolean;
+};
+export type RoleDefinition = {
+    readonly roleId: string;
+    readonly permissions: readonly Permission[];
+    /** Tool names or categories this role may discover and execute. */
+    readonly tools?: readonly string[];
+};
+export type AuditEvent = {
+    readonly kind: "denied" | "allowed-write";
+    readonly tenantId: string;
+    readonly principalId: string;
+    readonly action: string;
+    readonly resource: ResourceRef;
+    readonly reason?: string;
+};
+export type AuthorizationConfig = {
+    readonly roles: readonly RoleDefinition[];
+    /** Sink for denials and allowed external writes (docs/11 auditing). */
+    readonly audit?: (event: AuditEvent) => void;
+};
+/** The tenant predicate `scope()` produces — the same rule a Supabase RLS policy enforces. */
+export declare const tenantRlsFilter: (tenantId: string) => Readonly<Record<string, unknown>>;
+export declare const createAuthorizationPolicy: (config: AuthorizationConfig) => AuthorizationPolicy;
+/** Guard for the execution path: throws `forbidden` when the tool may not run. */
+export declare const assertToolAuthorized: (policy: AuthorizationPolicy, context: ExecutionContext, tool: {
+    readonly name: string;
+    readonly category: string;
+}) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/authorization/index.js

@@ -0,0 +1,76 @@
+/**
+ * Authorization port — `docs/11-authorization.md`. **Frozen v1.**
+ *
+ * A first-class port, not scattered `if` checks. The engine lands in REQ-004; this is the shape
+ * every store, tool and retrieval path takes decisions from. Imports only core + tool contracts —
+ * never an adapter.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+const WRITE_ACTIONS = new Set(["create", "update", "delete", "publish", "send", "execute"]);
+/** The tenant predicate `scope()` produces — the same rule a Supabase RLS policy enforces. */
+export const tenantRlsFilter = (tenantId) => ({
+    tenant_id: tenantId,
+});
+export const createAuthorizationPolicy = (config) => {
+    const roleMap = new Map(config.roles.map((r) => [r.roleId, r]));
+    const rolesOf = (ctx) => ctx.roleIds.map((id) => roleMap.get(id)).filter((r) => r !== undefined);
+    const matches = (p, action, type) => (p.action === "*" || p.action === action) && (p.resourceType === "*" || p.resourceType === type);
+    return {
+        async can(context, action, resource) {
+            const audit = (kind, reason) => config.audit?.({ kind, tenantId: context.tenantId, principalId: context.principalId, action, resource, ...(reason ? { reason } : {}) });
+            // Cross-tenant guard: a resource carrying another tenant's id is never visible.
+            const rt = resource.attributes?.["tenantId"];
+            if (typeof rt === "string" && rt !== context.tenantId) {
+                audit("denied", "cross-tenant");
+                return { allow: false, reason: "cross-tenant" };
+            }
+            // Tools are governed by the role's allow-list (name or category), so discovery and
+            // execution use the exact same rule.
+            if (resource.type === "tool") {
+                const allowed = new Set(rolesOf(context).flatMap((r) => r.tools ?? []));
+                const category = resource.attributes?.["category"];
+                const ok = (resource.id !== undefined && allowed.has(resource.id)) ||
+                    (typeof category === "string" && allowed.has(category));
+                if (!ok) {
+                    audit("denied", "tool not permitted");
+                    return { allow: false, reason: `tool ${resource.id ?? "?"} not permitted` };
+                }
+                audit("allowed-write");
+                return { allow: true };
+            }
+            const perm = rolesOf(context).flatMap((r) => r.permissions).find((p) => matches(p, action, resource.type));
+            if (!perm) {
+                audit("denied", "no permission");
+                return { allow: false, reason: `no permission for ${action} on ${resource.type}` };
+            }
+            if (WRITE_ACTIONS.has(action))
+                audit("allowed-write");
+            return perm.requiresApproval
+                ? { allow: true, obligations: [{ kind: "requires-approval" }] }
+                : { allow: true };
+        },
+        async filterTools(context, tools) {
+            const allowed = new Set(rolesOf(context).flatMap((r) => r.tools ?? []));
+            return tools.filter((t) => allowed.has(t.name) || allowed.has(t.category));
+        },
+        async scope(context) {
+            return { tenantId: context.tenantId, roleIds: context.roleIds, filter: tenantRlsFilter(context.tenantId) };
+        },
+    };
+};
+/** Guard for the execution path: throws `forbidden` when the tool may not run. */
+export const assertToolAuthorized = async (policy, context, tool) => {
+    const decision = await policy.can(context, "execute", {
+        type: "tool",
+        id: tool.name,
+        attributes: { category: tool.category },
+    });
+    if (!decision.allow) {
+        throw new AgentPlatformError({
+            code: "forbidden",
+            message: decision.reason ?? `Tool ${tool.name} is not authorized`,
+            retryable: false,
+        });
+    }
+};
+//# sourceMappingURL=index.js.map

package/dist/capabilities/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * What a runtime does, declared — #198.
+ *
+ * ## Why a declaration exists at all
+ *
+ * Capabilities were already switchable: `usage?`, `messages?`, `quota?`, `approvals?`, `questions?`,
+ * `citations?` are all optional, and a host that wants a lean automation runtime passes fewer of them. The
+ * mechanism is right. The ergonomics are not, because **an unwired capability and a deliberately disabled one
+ * are indistinguishable**, and that ambiguity is this codebase's most repeated defect: #157, #159, #161, #163,
+ * #165 and #185 were each a capability that existed, passed its tests, and was wired to nothing.
+ * `check-reachability.mjs` exists because of it — and it can only ever check *this* repository, never a
+ * customer's.
+ *
+ * ## Why not just booleans
+ *
+ * A boolean cannot carry its dependency. `memory: true` still needs a store, so true-with-nothing-wired is a
+ * crash or a silent no-op — the same failure with a friendlier spelling. Twelve booleans is also 4,096
+ * combinations, almost none of them ever exercised.
+ *
+ * ## So: both, cross-checked
+ *
+ * The host declares, the host wires, and `resolveCapabilities` refuses to return a runtime whose declaration and
+ * wiring disagree — **in either direction**. Declared-on-but-unwired is the obvious one. Wired-but-undeclared
+ * matters just as much: it means the declaration has drifted into a lie, and the next reader trusts it.
+ *
+ * One error listing every mismatch, never the first one found. A caller fixing these one restart at a time is
+ * why configuration surfaces get abandoned.
+ */
+/**
+ * The switchable capabilities.
+ *
+ * Deliberately **not** including approvals or quota enforcement. An automation with no human is a legitimate
+ * case, and a flag that removes the enforcement is not the way to express it — that is an approval *policy*
+ * which auto-approves a stated set of effects, and is auditable afterwards where a flag leaves no record. The
+ * difference is between "nobody had to approve this" and "we cannot tell whether anyone should have".
+ */
+export declare const CAPABILITIES: readonly ["history", "memory", "compaction", "citations", "questions", "skills", "mcp", "usage"];
+export type Capability = (typeof CAPABILITIES)[number];
+export type CapabilityState = "on" | "off";
+export type CapabilityMap = Readonly<Record<Capability, CapabilityState>>;
+/**
+ * What each capability cannot work without, by the name a host wires it under.
+ *
+ * Names rather than types, because the check is about *presence*: the compiler already proves a supplied store
+ * is the right shape, and what it cannot prove is that one was supplied at all.
+ */
+export declare const CAPABILITY_REQUIRES: Readonly<Record<Capability, readonly string[]>>;
+/**
+ * Named starting points, so the two common shapes are one line.
+ *
+ * A profile is **only** a set of defaults and must be expressible by writing the capabilities out — otherwise it
+ * is a second configuration language, and the two drift. `profileToMap` and a test hold that.
+ */
+export declare const PROFILES: {
+    /** A chat assistant: everything a person interacts with, on. */
+    readonly assistant: {
+        readonly history: "on";
+        readonly memory: "on";
+        readonly compaction: "on";
+        readonly citations: "on";
+        readonly questions: "on";
+        readonly skills: "on";
+        readonly mcp: "off";
+        readonly usage: "on";
+    };
+    /**
+     * A headless automation: no conversation, no person, no recall.
+     *
+     * `usage` stays on because an automation that runs unattended is precisely the one whose spend nobody is
+     * watching. Turning metering off by default there would be the expensive mistake.
+     */
+    readonly automation: {
+        readonly history: "off";
+        readonly memory: "off";
+        readonly compaction: "off";
+        readonly citations: "off";
+        readonly questions: "off";
+        readonly skills: "off";
+        readonly mcp: "off";
+        readonly usage: "on";
+    };
+};
+export type ProfileName = keyof typeof PROFILES;
+/** A profile as a plain map, so a caller can read a default before adopting it. */
+export declare const profileToMap: (profile: ProfileName) => CapabilityMap;
+export type ResolveCapabilitiesInput = {
+    readonly profile?: ProfileName;
+    /** Overrides on top of the profile, or the whole declaration when no profile is named. */
+    readonly capabilities?: Partial<CapabilityMap>;
+    /**
+     * The names the host actually wired, as supplied. A `Set` rather than the objects themselves: this function's
+     * job is the *cross-check*, and taking the objects would tempt it into validating their shapes, which the
+     * compiler already does better.
+     */
+    readonly wired: ReadonlySet<string>;
+};
+/**
+ * The effective capability map, or a refusal naming every disagreement.
+ *
+ * Absent from both profile and overrides means **off**. That direction is deliberate: a capability nobody
+ * mentioned is one nobody asked for, and defaulting to on would resurrect the problem this exists to solve — a
+ * feature quietly present, wired to nothing, until the day it matters.
+ */
+export declare const resolveCapabilities: (input: ResolveCapabilitiesInput) => CapabilityMap;
+/**
+ * ## What is deliberately *not* here yet: a point-of-use gate
+ *
+ * The obvious companion to `resolveCapabilities` is a `requireCapability(map, cap, forWhat)` that a code path
+ * calls to refuse when its capability is off. It was written, tested, and **removed before shipping** — because
+ * nothing could call it.
+ *
+ * No runtime object holds a capability map today: a host wires `ResolverDeps` by hand, and the map produced here
+ * is consulted by nobody. So the gate would have been exported, covered by its own tests, and reachable from
+ * nothing — which is #157, #159, #161, #163, #165 and #185, in the module whose entire purpose is to stop that.
+ * Leaving it in because it "will be used soon" is precisely the reasoning that produced those six.
+ *
+ * It returns with #196, when the composition root exists and there is something to consult the map. The check
+ * that matters until then is the construction-time one above, and that one *is* called.
+ */
+//# sourceMappingURL=index.d.ts.map