@retinue/agentkit 0.1.0

package/dist/capabilities/index.js

@@ -0,0 +1,167 @@
+/**
+ * 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.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+/**
+ * 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 const CAPABILITIES = [
+    "history",
+    "memory",
+    "compaction",
+    "citations",
+    "questions",
+    "skills",
+    "mcp",
+    "usage",
+];
+/**
+ * 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 const CAPABILITY_REQUIRES = {
+    history: ["messages"],
+    memory: ["principalMemory"],
+    // Two, and both: a summariser with nowhere to put the summary compacts on every turn and never remembers
+    // having done it.
+    compaction: ["summaries", "summarizer"],
+    citations: ["citations"],
+    questions: ["interactions"],
+    skills: ["skills"],
+    mcp: ["mcpConnections", "mcpClient"],
+    usage: ["usage"],
+};
+const OFF = Object.freeze(Object.fromEntries(CAPABILITIES.map((c) => [c, "off"])));
+/**
+ * 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 const PROFILES = {
+    /** A chat assistant: everything a person interacts with, on. */
+    assistant: {
+        history: "on",
+        memory: "on",
+        compaction: "on",
+        citations: "on",
+        questions: "on",
+        skills: "on",
+        mcp: "off",
+        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.
+     */
+    automation: {
+        history: "off",
+        memory: "off",
+        compaction: "off",
+        citations: "off",
+        questions: "off",
+        skills: "off",
+        mcp: "off",
+        usage: "on",
+    },
+};
+/** A profile as a plain map, so a caller can read a default before adopting it. */
+export const profileToMap = (profile) => ({ ...PROFILES[profile] });
+/**
+ * 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 const resolveCapabilities = (input) => {
+    const base = input.profile === undefined ? OFF : PROFILES[input.profile];
+    const effective = { ...base, ...(input.capabilities ?? {}) };
+    const unknown = Object.keys(input.capabilities ?? {}).filter((k) => !CAPABILITIES.includes(k));
+    const declaredNotWired = [];
+    const wiredNotDeclared = [];
+    for (const capability of CAPABILITIES) {
+        const needs = CAPABILITY_REQUIRES[capability];
+        const suppliedAll = needs.every((n) => input.wired.has(n));
+        const suppliedAny = needs.some((n) => input.wired.has(n));
+        if (effective[capability] === "on" && !suppliedAll) {
+            const missing = needs.filter((n) => !input.wired.has(n));
+            declaredNotWired.push(`${capability} is on but ${missing.join(" and ")} ${missing.length > 1 ? "were" : "was"} not supplied`);
+        }
+        /**
+         * `suppliedAny`, not `suppliedAll`, for the reverse direction.
+         *
+         * A host that wired half of what a capability needs and declared it off has still told us two different
+         * things, and the half-wiring is the more likely mistake — it usually means they meant to turn it on.
+         */
+        if (effective[capability] === "off" && suppliedAny) {
+            const supplied = needs.filter((n) => input.wired.has(n));
+            wiredNotDeclared.push(`${capability} is off but ${supplied.join(" and ")} ${supplied.length > 1 ? "were" : "was"} supplied`);
+        }
+    }
+    const problems = [
+        ...unknown.map((k) => `"${k}" is not a capability — the set is ${CAPABILITIES.join(", ")}`),
+        ...declaredNotWired,
+        ...wiredNotDeclared,
+    ];
+    if (problems.length === 0)
+        return Object.freeze(effective);
+    throw new AgentPlatformError({
+        code: "invalid_input",
+        message: `this runtime's capability declaration does not match what was wired:\n` +
+            problems.map((p) => `  - ${p}`).join("\n") +
+            `\nEither supply what the capability needs, or declare it off. A capability that is present but ` +
+            `undeclared is the defect this check exists to prevent: it works until the day nobody remembers it is there.`,
+        retryable: false,
+    });
+};
+/**
+ * ## 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.js.map

package/dist/capabilities/runtime.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The composition root — #196.
+ *
+ * `resolveCapabilities` validates a declaration against a set of wired names. It works, and it left two gaps that
+ * only a composition root can close.
+ *
+ * **The `wired` set was hand-written.** A host passed `new Set(["messages", "principalMemory", …])` beside the
+ * stores it supplied, so the cross-check compared a declaration against *another declaration*. Two lists that
+ * must agree, neither derived from the thing they describe — which is the shape of the problem, not a fix for it.
+ * Here the set is derived from the objects actually supplied, so there is one statement of intent and one of
+ * fact.
+ *
+ * **A capability that is off was unenforced.** Nothing consulted the map, so "off" meant "the host did not wire
+ * it" and any code path that reached for it got `undefined`. `requireCapability` was written for this and
+ * removed in 684bb1d for having no caller — which was correct then and is fixable now.
+ *
+ * The fix is that **access is the gate**. `runtime.stores.messages` throws when `history` is off, naming the
+ * capability. Not a function a caller must remember to call first: the ones who forget are exactly the six
+ * defects this module exists for. Every consumer of a store goes through the same property.
+ */
+import type { RunEventLog } from "../core/events.js";
+import type { InteractionStore, MessageStore, RunStore, SkillStore, ThreadSummaryStore, UsageStore } from "../persistence/index.js";
+import type { PrincipalMemoryStore } from "../principal-memory/index.js";
+import type { ThreadSummarizer } from "../context/compaction.js";
+import type { CitationEmitter } from "../citations/index.js";
+import type { McpClient, McpConnectionStore } from "../mcp/provider.js";
+import { type Capability, type CapabilityMap, type ProfileName } from "./index.js";
+/**
+ * What every runtime needs, capability or not.
+ *
+ * A run must be durable — that is the floor, not a feature, and a runtime without it is a library for calling a
+ * model. `eventLog` is separate and optional: a run without one still executes, it is simply unobservable while
+ * it does, which is a legitimate trade for a batch job nobody is watching.
+ */
+export type RuntimeFloor = {
+    readonly runs: RunStore;
+    readonly eventLog?: RunEventLog;
+};
+/**
+ * The capability-governed dependencies, keyed by the names `CAPABILITY_REQUIRES` uses.
+ *
+ * The key names are load-bearing: they are what the derived `wired` set is built from, so a key here and an
+ * entry in `CAPABILITY_REQUIRES` must spell the same thing. A test holds that, because a typo would silently
+ * mean "not wired" and the capability would be refused for a reason nobody could see.
+ */
+export type RuntimeStores = {
+    readonly messages?: MessageStore;
+    readonly principalMemory?: PrincipalMemoryStore;
+    readonly summaries?: ThreadSummaryStore;
+    readonly interactions?: InteractionStore;
+    readonly skills?: SkillStore;
+    readonly usage?: UsageStore;
+    readonly citations?: CitationEmitter;
+    readonly mcpConnections?: McpConnectionStore;
+};
+export type RuntimeServices = {
+    readonly summarizer?: ThreadSummarizer;
+    readonly mcpClient?: McpClient;
+};
+export type CreateRuntimeInput = {
+    readonly profile?: ProfileName;
+    readonly capabilities?: Partial<CapabilityMap>;
+    readonly floor: RuntimeFloor;
+    readonly stores?: RuntimeStores;
+    readonly services?: RuntimeServices;
+};
+export type Runtime = {
+    readonly capabilities: CapabilityMap;
+    /** The floor, always available. */
+    readonly floor: RuntimeFloor;
+    /**
+     * Capability-governed access. Reading a name whose capability is off **throws**, naming the capability.
+     *
+     * Reading, not calling — so a host cannot get a reference to a store it has turned off and use it later, which
+     * is the loophole a `require()`-style check leaves open.
+     */
+    readonly stores: Required<RuntimeStores>;
+    readonly services: Required<RuntimeServices>;
+    /** True when the capability is on. For a host that wants to branch rather than be refused. */
+    enabled(capability: Capability): boolean;
+};
+/**
+ * Assemble a runtime, or refuse to.
+ *
+ * The declaration and the wiring are cross-checked here — every mismatch in one error — so a misconfigured
+ * runtime fails at construction rather than three hours into production.
+ */
+export declare const createRuntime: (input: CreateRuntimeInput) => Runtime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/capabilities/runtime.js

@@ -0,0 +1,84 @@
+/**
+ * The composition root — #196.
+ *
+ * `resolveCapabilities` validates a declaration against a set of wired names. It works, and it left two gaps that
+ * only a composition root can close.
+ *
+ * **The `wired` set was hand-written.** A host passed `new Set(["messages", "principalMemory", …])` beside the
+ * stores it supplied, so the cross-check compared a declaration against *another declaration*. Two lists that
+ * must agree, neither derived from the thing they describe — which is the shape of the problem, not a fix for it.
+ * Here the set is derived from the objects actually supplied, so there is one statement of intent and one of
+ * fact.
+ *
+ * **A capability that is off was unenforced.** Nothing consulted the map, so "off" meant "the host did not wire
+ * it" and any code path that reached for it got `undefined`. `requireCapability` was written for this and
+ * removed in 684bb1d for having no caller — which was correct then and is fixable now.
+ *
+ * The fix is that **access is the gate**. `runtime.stores.messages` throws when `history` is off, naming the
+ * capability. Not a function a caller must remember to call first: the ones who forget are exactly the six
+ * defects this module exists for. Every consumer of a store goes through the same property.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { CAPABILITY_REQUIRES } from "./index.js";
+import { resolveCapabilities } from "./index.js";
+/** Which capability governs which supplied name — the inverse of `CAPABILITY_REQUIRES`. */
+const GOVERNED_BY = Object.freeze(Object.fromEntries(Object.entries(CAPABILITY_REQUIRES).flatMap(([capability, needs]) => needs.map((name) => [name, capability]))));
+const refuse = (name, capability) => {
+    throw new AgentPlatformError({
+        code: "invalid_input",
+        message: `this runtime has "${capability}" off, so ${name} is not available. Something reached for it anyway, ` +
+            `which means a code path is running that this configuration does not support — turn ${capability} on and ` +
+            `supply ${CAPABILITY_REQUIRES[capability].join(" and ")}, or do not take that path.`,
+        retryable: false,
+    });
+};
+/**
+ * A proxy rather than an object of getters.
+ *
+ * The same decision `lazyCoordinator` took, for the same reason: enumerating the keys means a dependency added
+ * later is silently absent from the gate, and silently-absent is the failure being designed against. One rule
+ * covers every name, present and future.
+ */
+const governed = (supplied, capabilities, label) => new Proxy(supplied, {
+    get(target, property) {
+        if (typeof property !== "string")
+            return Reflect.get(target, property);
+        const capability = GOVERNED_BY[property];
+        if (capability !== undefined && capabilities[capability] !== "on")
+            refuse(`${label}.${property}`, capability);
+        return Reflect.get(target, property);
+    },
+});
+/**
+ * Assemble a runtime, or refuse to.
+ *
+ * The declaration and the wiring are cross-checked here — every mismatch in one error — so a misconfigured
+ * runtime fails at construction rather than three hours into production.
+ */
+export const createRuntime = (input) => {
+    const stores = input.stores ?? {};
+    const services = input.services ?? {};
+    /**
+     * Derived, not declared.
+     *
+     * `Object.entries` over what was supplied, keeping only the defined values — because an explicit
+     * `messages: undefined` is how a spread of optional config produces a key that means nothing, and treating
+     * that as wired would refuse a runtime for a store that is not there.
+     */
+    const wired = new Set([...Object.entries(stores), ...Object.entries(services)]
+        .filter(([, value]) => value !== undefined)
+        .map(([name]) => name));
+    const capabilities = resolveCapabilities({
+        ...(input.profile === undefined ? {} : { profile: input.profile }),
+        ...(input.capabilities === undefined ? {} : { capabilities: input.capabilities }),
+        wired,
+    });
+    return {
+        capabilities,
+        floor: input.floor,
+        stores: governed(stores, capabilities, "stores"),
+        services: governed(services, capabilities, "services"),
+        enabled: (capability) => capabilities[capability] === "on",
+    };
+};
+//# sourceMappingURL=runtime.js.map

package/dist/citations/index.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Citations and per-claim provenance — REQ-030 (#137).
+ *
+ * `research-and-citation` already says what should happen. This makes it structural, and the structure carries
+ * four decisions worth stating.
+ *
+ * **A citation is a snapshot, not a pointer.** `excerpt`, `title` and `retrievedAt` live on the part. AC-4
+ * requires an answer given months ago to stay auditable *after the source is gone* — a document deleted, a URL
+ * dead, a chunk re-indexed under a new id — and a citation that resolved by fetching would stop being evidence
+ * exactly when someone needs it. The duplication is the feature.
+ *
+ * **Groundedness is derived from the citation graph**, not flagged on the text. A text part is grounded exactly
+ * when some citation names it in `supports`. A boolean on the text part would be a second place for the same
+ * fact, and the two would drift the first time a citation was withheld — leaving a claim that says "grounded"
+ * with nothing behind it, which is worse than an honestly ungrounded one.
+ *
+ * **Permission is re-checked at citation time.** AC-5, and the reason is precise: retrieval and rendering are
+ * different moments, and a permission can change between them. A citation emitted on the strength of a
+ * retrieval check is a citation that can outlive the access that justified it.
+ *
+ * **One shape for retrieval and web research.** AC-6. Two part types would mean two renderers, two schemas and
+ * eventually two behaviours for "click the citation".
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { MessagePartId } from "../core/ids.js";
+import type { CitationOrigin, CitationPart, MessagePart } from "../core/content-parts.js";
+import type { AuthorizationPolicy } from "../authorization/index.js";
+import type { RetrievalHit } from "../knowledge/retrieval.js";
+/** The current citation payload version. Bumped from 1 by #137, which added origin, excerpt and supports. */
+export declare const CITATION_SCHEMA_VERSION = 2;
+/**
+ * Trim an excerpt to the cap without cutting a word in half.
+ *
+ * A citation ending mid-word reads as corrupt, and a reader cannot tell whether the source said something else.
+ * The ellipsis is explicit so a truncated excerpt is visibly truncated rather than silently shorter than what
+ * was read.
+ */
+export declare const boundExcerpt: (text: string, max?: number) => string;
+export type CitationCandidate = {
+    readonly origin: CitationOrigin;
+    readonly excerpt: string;
+    readonly retrievedAt: string;
+    readonly supports: readonly MessagePartId[];
+    readonly charRange?: {
+        readonly start: number;
+        readonly end: number;
+    };
+    /**
+     * The subject the reader must be entitled to.
+     *
+     * Required for a retrieval citation and absent for a web one — a public URL has no subject to check. Kept
+     * *outside* the part on purpose: it is an input to the emission decision, not something a stored citation
+     * should carry, because a stale subject on a durable part is a permission claim nobody re-evaluates.
+     */
+    readonly authSubject?: string;
+};
+/** A citation built from a retrieval hit. The passage fields come from the hit, so they cannot disagree. */
+export declare const citationFromRetrieval: (input: {
+    readonly hit: RetrievalHit;
+    readonly supports: readonly MessagePartId[];
+    readonly retrievedAt: string;
+    readonly charRange?: {
+        readonly start: number;
+        readonly end: number;
+    };
+}) => CitationCandidate;
+/**
+ * A citation built from a web passage.
+ *
+ * Shaped to accept ShareFlow's `SourcePassage` without adaptation — `url`, `retrievedAt`, `excerpt` — because
+ * AC-6 is only true if the two paths really do produce one thing rather than two things that look alike.
+ */
+export declare const citationFromWeb: (input: {
+    readonly passage: {
+        readonly url: string;
+        readonly retrievedAt: string;
+        readonly excerpt: string;
+    };
+    readonly title?: string;
+    readonly supports: readonly MessagePartId[];
+}) => CitationCandidate;
+export type EmittedCitations = {
+    readonly parts: readonly CitationPart[];
+    /**
+     * How many candidates were dropped for lack of access.
+     *
+     * Reported rather than silent. A withheld citation leaves its claim looking ungrounded, and a caller that
+     * cannot tell the difference between "nothing supported this" and "you may not see what supported this" will
+     * present the two identically — so the count is here for a caller that wants to drop the claim instead.
+     */
+    readonly withheld: number;
+};
+export type CitationEmitterDeps = {
+    /**
+     * AC-5, enforced rather than asserted.
+     *
+     * **Required.** An emitter that would run without a policy is one someone constructs without one, at which
+     * point every citation is emitted regardless of access — and a citation carries an excerpt, so that leaks the
+     * text and not merely the existence of the source.
+     */
+    readonly authorization: AuthorizationPolicy;
+    readonly clock?: () => string;
+    readonly partId?: () => string;
+};
+export declare const createCitationEmitter: (deps: CitationEmitterDeps) => {
+    /**
+     * Turn candidates into parts, dropping any the reader may not open.
+     *
+     * Checked here and not only at retrieval, because the two are different moments. A permission revoked in
+     * between is exactly the case the test steps name, and a citation emitted on a retrieval-time check would
+     * survive it.
+     */
+    emit(context: ExecutionContext, candidates: readonly CitationCandidate[]): Promise<EmittedCitations>;
+    /**
+     * Whether this reader may be shown this citation.
+     *
+     * A web citation needs no check: its URL is public by construction, and asking a policy about it would be
+     * asking about a resource the policy has never heard of — which most policies answer by denying, silently
+     * suppressing every web citation.
+     */
+    mayCite(context: ExecutionContext, candidate: CitationCandidate): Promise<boolean>;
+};
+export type CitationEmitter = ReturnType<typeof createCitationEmitter>;
+/**
+ * The parts a message's citations ground — AC-3.
+ *
+ * Derived from the citation graph, so there is one source of truth. A caller renders a text part differently
+ * when its id is in this set; nothing has to inspect the prose.
+ */
+export declare const groundedPartIds: (parts: readonly MessagePart[]) => ReadonlySet<string>;
+/** Citations that ground a given part, in the order they appear. For rendering markers next to a claim. */
+export declare const citationsFor: (parts: readonly MessagePart[], partId: string) => readonly CitationPart[];
+/**
+ * A citation that grounds nothing.
+ *
+ * Worth finding, because it is the shape a bug takes: a producer that emitted citations without wiring them to
+ * the claims they support leaves an answer that *looks* cited — markers in a list at the bottom — while no
+ * individual statement is traceable, which is the failure REQ-030 exists to prevent.
+ */
+export declare const danglingCitations: (parts: readonly MessagePart[]) => readonly CitationPart[];
+/**
+ * What a citation resolves to — AC-2.
+ *
+ * Returned from the *stored part alone*, with no lookup, which is what makes AC-4 hold: an audit months later
+ * gets the same answer whether or not the source still exists. `live` says whether following it further is
+ * possible, so a reader is told "this is what was read, and the source is gone" rather than being handed a
+ * broken link.
+ */
+export type ResolvedCitation = {
+    readonly excerpt: string;
+    readonly retrievedAt: string;
+    /** Human-readable: a heading path, or a title, or the URL. What a reader sees next to the claim. */
+    readonly label: string;
+    /** Where to go, if anywhere. A chunk id for retrieval, the URL for web. */
+    readonly target: string;
+    readonly kind: CitationOrigin["kind"];
+};
+export declare const resolveCitation: (part: CitationPart) => ResolvedCitation;
+/** Thrown when a producer tries to cite without an excerpt. A citation with no text is not evidence. */
+export declare const assertCitable: (candidate: CitationCandidate) => void;
+//# sourceMappingURL=index.d.ts.map