@retinue/agentkit 0.1.0

package/dist/server/sse-route.js

@@ -0,0 +1,282 @@
+/**
+ * HTTP SSE endpoint for run events (#109).
+ *
+ * `@retinue/agentkit`'s `graphql/sse.ts` already produces ready-to-write frames and maps
+ * `Last-Event-ID` to a resume cursor, deliberately without an HTTP dependency. This is the route that
+ * serves it, in the workspace where the server dependency already lives.
+ *
+ * Two design decisions carry the weight, and they pull against each other:
+ *
+ * **Backpressure (AC-6) wants a pull-based stream** — produce only when the consumer asks.
+ * **Keep-alives (AC-5) want the server to emit without being asked.** Resolved by racing inside
+ * `pull`: each pull awaits the next event *or* a keep-alive timeout. Nothing is produced without
+ * demand, so a slow client stops being pulled and backpressure reaches the source instead of a buffer;
+ * and an idle stream still emits a comment per interval. A `setInterval` enqueuing comments regardless
+ * of demand would satisfy AC-5 and quietly break AC-6 — a stalled client would accumulate one comment
+ * per interval, forever.
+ */
+import { asId } from "../index.js";
+import { cursorFromLastEventId, openRunEventSse } from "../graphql/sse.js";
+/** A comment frame. Intermediaries see bytes; clients ignore it. */
+const KEEP_ALIVE = ": keep-alive\n\n";
+const SSE_HEADERS = {
+    "content-type": "text/event-stream; charset=utf-8",
+    "cache-control": "no-cache, no-transform",
+    connection: "keep-alive",
+    // Without this an nginx in front buffers the stream and the client sees nothing until it ends,
+    // which for a live run is indistinguishable from the feature not working.
+    "x-accel-buffering": "no",
+};
+/**
+ * Read `runId` / `conversationId` / `after` out of a GraphQL operation body, tolerantly.
+ *
+ * Tolerant on purpose: a malformed or absent body is not an error here, because the query-parameter
+ * form is equally valid. A body that cannot be parsed simply yields no identifiers, and the caller
+ * then fails with the same 400 it would have for a missing parameter.
+ */
+const readOperationVariables = async (request) => {
+    const empty = { runId: null, conversationId: null, after: null };
+    if (request.method !== "POST")
+        return empty;
+    try {
+        const body = (await request.clone().json());
+        const variables = body.variables ?? {};
+        const str = (key) => {
+            const value = variables[key];
+            return typeof value === "string" ? value : typeof value === "number" ? String(value) : null;
+        };
+        return { runId: str("runId"), conversationId: str("conversationId"), after: str("after") };
+    }
+    catch {
+        return empty;
+    }
+};
+export const createRunEventSseRoute = (options) => {
+    const keepAliveMs = options.keepAliveMs ?? 15_000;
+    const path = options.path ?? "/runs/events";
+    return {
+        path,
+        async handle(request) {
+            /**
+             * Identifiers from either shape, because two kinds of consumer reach this route.
+             *
+             * A `graphql-sse` client POSTs `{query, variables}` with `accept: text/event-stream` — that is
+             * what its distinct-connections mode does, and it never looks at query parameters. #109 accepted
+             * only query parameters, so #111's frame compliance was real while the *request* side still could
+             * not be reached by a real client. An `EventSource`, by contrast, can only issue a GET with a URL.
+             *
+             * The query text is deliberately not executed: this is a streaming route, not a GraphQL executor.
+             * See the open question on #112.
+             */
+            const url = new URL(request.url);
+            const fromBody = await readOperationVariables(request);
+            const runIdParam = url.searchParams.get("runId") ?? fromBody.runId;
+            const conversationIdParam = url.searchParams.get("conversationId") ?? fromBody.conversationId;
+            if (runIdParam === null || conversationIdParam === null) {
+                return new Response("runId and conversationId are required", { status: 400 });
+            }
+            const execution = await options.authenticate(request);
+            if (execution === null || execution === undefined) {
+                return new Response("Unauthenticated", { status: 401 });
+            }
+            const conversationId = asId(conversationIdParam);
+            const runId = asId(runIdParam);
+            /**
+             * Ownership from data, unconditionally.
+             *
+             * Every store read is tenant-scoped, so a conversation belonging to another tenant simply is not
+             * found — the caller cannot forget this check because the route performs it before anything else.
+             * A callback alone would have left the cross-tenant case, which is the dangerous one, to the
+             * caller's policy.
+             */
+            const conversation = await options.deps.conversations.findById({
+                tenantId: execution.tenantId,
+                id: conversationId,
+            });
+            // 404, not 403. A 403 confirms the conversation exists, which across tenants is itself the leak.
+            if (conversation === null)
+                return new Response("Not found", { status: 404 });
+            if (options.authorizeConversation) {
+                const allowed = await options.authorizeConversation(execution, conversationId);
+                // Also 404 rather than 403, for the same reason: an unentitled user learning a conversation
+                // exists is information they should not have.
+                if (!allowed)
+                    return new Response("Not found", { status: 404 });
+            }
+            /**
+             * Resume cursor, from whichever source the consumer has.
+             *
+             * `Last-Event-ID` first, because a browser `EventSource` resends it automatically and that is the
+             * only mechanism it has. Then `after` from the operation variables — the graphql-sse client
+             * **never sends `Last-Event-ID`** (it is absent from its source entirely; it retries with backoff
+             * and re-subscribes from the start), so a consumer that wants resume has to pass a cursor itself.
+             * That is the one accommodation beyond the raw protocol, recorded for #112's AC-6.
+             */
+            const after = request.headers.get("last-event-id") !== null
+                ? cursorFromLastEventId(request.headers.get("last-event-id"))
+                : cursorFromLastEventId(fromBody.after);
+            // Polled by `openRunEventStream`, so a Web AbortSignal needs adapting rather than passing.
+            // Both directions matter: the request's signal (the client dropped) and the stream's `cancel`
+            // (the consumer stopped reading without closing) — the second is the case that leaks a
+            // generator.
+            let aborted = false;
+            const signal = {
+                get aborted() {
+                    return aborted || request.signal.aborted;
+                },
+            };
+            /**
+             * A promise that settles when this stream is abandoned, and the reason it has to exist.
+             *
+             * `openRunEventStream` polls `signal.aborted`, which only helps *between* events. When it is
+             * parked awaiting the live source there is nothing to poll: an async generator suspended at an
+             * `await` cannot run its `finally` until that await settles, so calling `.return()` on it does
+             * not interrupt it — it queues. Awaiting that return in `cancel()` therefore hangs forever,
+             * which is exactly what the first version of this route did.
+             *
+             * So the live source is wrapped to race each read against this promise. Cancelling resolves it,
+             * the wrapper returns, and its `finally` releases the underlying subscription.
+             */
+            let abandon = () => { };
+            const abandoned = new Promise((resolve) => {
+                abandon = () => resolve("abandoned");
+            });
+            const live = {
+                subscribe(channel) {
+                    const inner = options.deps.live.subscribe(channel)[Symbol.asyncIterator]();
+                    return {
+                        async *[Symbol.asyncIterator]() {
+                            try {
+                                for (;;) {
+                                    const next = await Promise.race([inner.next(), abandoned]);
+                                    if (next === "abandoned" || next.done === true)
+                                        return;
+                                    yield next.value;
+                                }
+                            }
+                            finally {
+                                // Not awaited: a parked in-memory subscriber cannot be interrupted mid-await, so
+                                // awaiting here would reintroduce the hang. The subscription is released when the
+                                // inner generator next wakes.
+                                void inner.return?.(undefined);
+                            }
+                        },
+                    };
+                },
+            };
+            const frames = openRunEventSse({
+                tenantId: execution.tenantId,
+                runId,
+                conversationId,
+                after,
+                log: options.deps.eventLog,
+                live,
+                ...(options.deps.channelFor ? { channelFor: options.deps.channelFor } : {}),
+                signal,
+            })[Symbol.asyncIterator]();
+            const encoder = new TextEncoder();
+            /**
+             * One reader owns the generator; `pull` takes from a **one-slot** handoff.
+             *
+             * The obvious implementation — race `frames.next()` against a keep-alive timer inside `pull` —
+             * has a subtle flaw that cost real debugging time. When the keep-alive wins, the outstanding
+             * `next()` must be retained, or the event it eventually yields is delivered to an abandoned
+             * promise and lost. Retaining it is not enough either: a generator that yields and then returns
+             * (which is exactly what a terminal event does) can deliver its value to one queued `next()` and
+             * `done` to another, so the frame disappears and the stream just closes. Observed: `yielding 1`
+             * followed immediately by `terminal`, with no frame ever reaching the client.
+             *
+             * A single reader removes the class of problem. It reads one frame, parks until `pull` takes it,
+             * then reads the next — so the generator has exactly one consumer and exactly one outstanding
+             * `next()`, and the one-slot capacity is what keeps AC-6 true: a client that stops reading stops
+             * the reader after one frame rather than draining the source into a buffer.
+             */
+            let slot = null;
+            let finished = false;
+            let failure = null;
+            let notifyPull = null;
+            let notifyReader = null;
+            const wake = (fn) => fn?.();
+            const readerLoop = (async () => {
+                try {
+                    for (;;) {
+                        if (signal.aborted)
+                            return;
+                        const next = await frames.next();
+                        if (next.done === true)
+                            return;
+                        slot = next.value;
+                        wake(notifyPull);
+                        // Park until `pull` empties the slot. This is the backpressure: no further read happens
+                        // while the consumer has not taken what is already there.
+                        if (slot !== null) {
+                            await new Promise((resolve) => {
+                                notifyReader = resolve;
+                            });
+                            notifyReader = null;
+                        }
+                    }
+                }
+                catch (error) {
+                    failure = error;
+                }
+                finally {
+                    finished = true;
+                    wake(notifyPull);
+                    abandon();
+                    void frames.return?.(undefined);
+                }
+            })();
+            const body = new ReadableStream({
+                async pull(controller) {
+                    for (;;) {
+                        if (failure !== null) {
+                            controller.error(failure);
+                            return;
+                        }
+                        if (slot !== null) {
+                            const frame = slot;
+                            slot = null;
+                            wake(notifyReader);
+                            controller.enqueue(encoder.encode(frame));
+                            return;
+                        }
+                        if (finished || signal.aborted) {
+                            controller.close();
+                            return;
+                        }
+                        // Nothing waiting: emit a keep-alive if the interval elapses first. Only ever reached on
+                        // demand, so an idle stream produces one comment per pull rather than one per interval.
+                        let timer;
+                        const armed = new Promise((resolve) => {
+                            timer = setTimeout(() => resolve("tick"), keepAliveMs);
+                        });
+                        const arrival = new Promise((resolve) => {
+                            notifyPull = () => resolve("frame");
+                        });
+                        const outcome = await Promise.race([arrival, armed]);
+                        if (timer !== undefined)
+                            clearTimeout(timer);
+                        notifyPull = null;
+                        if (outcome === "tick") {
+                            controller.enqueue(encoder.encode(KEEP_ALIVE));
+                            return;
+                        }
+                        // A frame (or the end) arrived; loop once to handle whichever it was.
+                    }
+                },
+                cancel() {
+                    // Flip the polled flag, settle the abandonment promise so the live wrapper unwinds, and let
+                    // the reader loop finish on its own. Not awaited: a parked source cannot be interrupted
+                    // mid-await, and awaiting here is what hangs.
+                    aborted = true;
+                    abandon();
+                    wake(notifyReader);
+                    void readerLoop;
+                },
+            });
+            return new Response(body, { status: 200, headers: SSE_HEADERS });
+        },
+    };
+};
+//# sourceMappingURL=sse-route.js.map

package/dist/skills/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Skills — `docs/03-intelligence-runtime.md`.
+ *
+ * A skill is a compact catalog entry plus a lazily loaded instruction body. Only the
+ * entry sits in context; the body arrives when the model calls `load_skill`.
+ *
+ * Two rules the type system helps enforce:
+ *
+ * 1. Arbitrary skill scripts are disabled by default — a skill is instructions and
+ *    data, never executable code.
+ * 2. A tenant-authored body is untrusted text. It cannot grant a tool, lower an effect
+ *    classification or bypass an approval; it only shapes how the model works.
+ */
+import type { SkillId, TenantId } from "../core/ids.js";
+export declare const SKILL_SOURCES: readonly ["built-in", "tenant", "plugin"];
+export type SkillSource = (typeof SKILL_SOURCES)[number];
+export type SkillStatus = "draft" | "active" | "archived";
+/** What discovery puts in context. Deliberately excludes the body. */
+export type SkillCatalogEntry = {
+    readonly id: SkillId;
+    /** Slug form, matching the existing workspace-skill constraint. */
+    readonly name: string;
+    readonly description: string;
+    readonly source: SkillSource;
+    readonly version: number;
+};
+export type SkillVersion = SkillCatalogEntry & {
+    readonly instructions: string;
+    readonly status: SkillStatus;
+    readonly tenantId?: TenantId;
+    readonly createdAt: string;
+    readonly createdBy?: string;
+};
+/**
+ * Limits mirroring the constraints already enforced on `workspace_agent_skills`, so a
+ * ported tenant skill cannot violate them on the way in.
+ */
+export declare const SKILL_LIMITS: {
+    readonly namePattern: RegExp;
+    readonly nameMaxLength: 64;
+    readonly descriptionMinLength: 20;
+    readonly descriptionMaxLength: 1024;
+    readonly instructionsMaxLength: 20000;
+    /** Per tenant. */
+    readonly maxSkills: 25;
+    /** Per run, to bound what `load_skill` can pull into context. */
+    readonly maxLoadedPerRun: 5;
+};
+/**
+ * Resolution layers built-in skills first, then tenant skills, so a tenant skill of the
+ * same name shadows a built-in one — matching the current `build_skills_for` behaviour.
+ */
+export interface SkillResolver {
+    listCatalog(input: {
+        tenantId: TenantId;
+        assigned: readonly string[];
+        allowTenantSkills: boolean;
+    }): Promise<readonly SkillCatalogEntry[]>;
+    /** Pins to an exact version so a mid-run edit cannot change behaviour. */
+    loadBody(input: {
+        tenantId: TenantId;
+        name: string;
+        version: number;
+    }): Promise<SkillVersion>;
+}
+export * from "./resolver.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/skills/index.js

@@ -0,0 +1,31 @@
+/**
+ * Skills — `docs/03-intelligence-runtime.md`.
+ *
+ * A skill is a compact catalog entry plus a lazily loaded instruction body. Only the
+ * entry sits in context; the body arrives when the model calls `load_skill`.
+ *
+ * Two rules the type system helps enforce:
+ *
+ * 1. Arbitrary skill scripts are disabled by default — a skill is instructions and
+ *    data, never executable code.
+ * 2. A tenant-authored body is untrusted text. It cannot grant a tool, lower an effect
+ *    classification or bypass an approval; it only shapes how the model works.
+ */
+export const SKILL_SOURCES = ["built-in", "tenant", "plugin"];
+/**
+ * Limits mirroring the constraints already enforced on `workspace_agent_skills`, so a
+ * ported tenant skill cannot violate them on the way in.
+ */
+export const SKILL_LIMITS = {
+    namePattern: /^[a-z0-9]+(-[a-z0-9]+)*$/,
+    nameMaxLength: 64,
+    descriptionMinLength: 20,
+    descriptionMaxLength: 1024,
+    instructionsMaxLength: 20_000,
+    /** Per tenant. */
+    maxSkills: 25,
+    /** Per run, to bound what `load_skill` can pull into context. */
+    maxLoadedPerRun: 5,
+};
+export * from "./resolver.js";
+//# sourceMappingURL=index.js.map

package/dist/skills/resolver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Skill resolution & per-run recording — `docs/03-intelligence-runtime.md` → Skills.
+ *
+ * A skill is a compact catalog entry plus a lazily loaded instruction body. Only the entry sits in
+ * context; the body arrives when the model calls `load_skill`. Resolution layers built-in skills
+ * first, then tenant skills, so a tenant skill of the same name shadows a built-in one. Two rules
+ * are enforced structurally: a skill is instructions and data — never executable code — and a
+ * tenant body is untrusted text that cannot grant a tool or lower an effect. And every load is
+ * recorded against the run, so skill versions are auditable per run.
+ */
+import type { SkillStore } from "../persistence/index.js";
+import { type SkillResolver, type SkillSource, type SkillVersion } from "./index.js";
+/**
+ * Validate a tenant-authored skill against the same limits as `workspace_agent_skills`, so a ported
+ * skill cannot violate them on the way in. Returns the value; throws `invalid_input` on any breach.
+ * There is no executable field to validate — a skill body is always plain instructions.
+ */
+export declare const validateSkillInput: (skill: SkillVersion) => SkillVersion;
+/**
+ * Resolver over a static built-in set plus a tenant `SkillStore`. Tenant skills shadow built-ins of
+ * the same name. `listCatalog` returns compact entries only (never bodies); `loadBody` pins to an
+ * exact version so a mid-run edit cannot change behaviour.
+ */
+export declare const createSkillResolver: (config: {
+    readonly builtIn: readonly SkillVersion[];
+    readonly store: SkillStore;
+}) => SkillResolver;
+/** What a run records for each skill it loaded — the audit trail of "skill versions per run". */
+export type SkillLoadRecord = {
+    readonly name: string;
+    readonly version: number;
+    readonly source: SkillSource;
+    readonly loadedAt: string;
+};
+/**
+ * Per-run skill loader: loads a body on demand, enforces `maxLoadedPerRun`, and records every load
+ * so the run's manifest of skill versions is complete and auditable. Loading the same skill twice
+ * is idempotent and does not count against the limit again.
+ */
+export declare const createRunSkillTracker: (config: {
+    readonly resolver: SkillResolver;
+    readonly maxLoadedPerRun?: number;
+    readonly clock?: () => string;
+}) => {
+    load(input: {
+        readonly tenantId: string;
+        readonly runId: string;
+        readonly name: string;
+        readonly version: number;
+    }): Promise<SkillVersion>;
+    /** The skill versions loaded during a run — recorded on the run per the acceptance criteria. */
+    recorded(runId: string): readonly SkillLoadRecord[];
+};
+//# sourceMappingURL=resolver.d.ts.map

package/dist/skills/resolver.js

@@ -0,0 +1,121 @@
+/**
+ * Skill resolution & per-run recording — `docs/03-intelligence-runtime.md` → Skills.
+ *
+ * A skill is a compact catalog entry plus a lazily loaded instruction body. Only the entry sits in
+ * context; the body arrives when the model calls `load_skill`. Resolution layers built-in skills
+ * first, then tenant skills, so a tenant skill of the same name shadows a built-in one. Two rules
+ * are enforced structurally: a skill is instructions and data — never executable code — and a
+ * tenant body is untrusted text that cannot grant a tool or lower an effect. And every load is
+ * recorded against the run, so skill versions are auditable per run.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import {} from "./index.js";
+import { SKILL_LIMITS } from "./index.js";
+const invalid = (message) => new AgentPlatformError({ code: "invalid_input", message, retryable: false });
+/**
+ * Validate a tenant-authored skill against the same limits as `workspace_agent_skills`, so a ported
+ * skill cannot violate them on the way in. Returns the value; throws `invalid_input` on any breach.
+ * There is no executable field to validate — a skill body is always plain instructions.
+ */
+export const validateSkillInput = (skill) => {
+    if (!SKILL_LIMITS.namePattern.test(skill.name) || skill.name.length > SKILL_LIMITS.nameMaxLength)
+        throw invalid(`Skill name "${skill.name}" is not a valid slug`);
+    if (skill.description.length < SKILL_LIMITS.descriptionMinLength ||
+        skill.description.length > SKILL_LIMITS.descriptionMaxLength)
+        throw invalid(`Skill "${skill.name}" description length is out of bounds`);
+    if (skill.instructions.length > SKILL_LIMITS.instructionsMaxLength)
+        throw invalid(`Skill "${skill.name}" instructions exceed ${SKILL_LIMITS.instructionsMaxLength} chars`);
+    return skill;
+};
+const toEntry = (s) => ({
+    id: s.id,
+    name: s.name,
+    description: s.description,
+    source: s.source,
+    version: s.version,
+});
+/**
+ * Resolver over a static built-in set plus a tenant `SkillStore`. Tenant skills shadow built-ins of
+ * the same name. `listCatalog` returns compact entries only (never bodies); `loadBody` pins to an
+ * exact version so a mid-run edit cannot change behaviour.
+ */
+export const createSkillResolver = (config) => {
+    const builtInByName = new Map(config.builtIn.map((s) => [s.name, s]));
+    return {
+        async listCatalog({ tenantId, assigned, allowTenantSkills }) {
+            const assignedSet = new Set(assigned);
+            const byName = new Map();
+            // Built-ins first, and only the active ones.
+            //
+            // The store adapters already filter discovery to the latest *active* version per name —
+            // deliberate and tested: "a run pinned to an archived version keeps working and no new run picks
+            // it up." This layer did not, so `status` was load-bearing for a tenant skill and inert for a
+            // built-in. Same field, two meanings, which is an inconsistency rather than a decision (#122).
+            for (const s of config.builtIn)
+                if (s.status === "active" && assignedSet.has(s.name))
+                    byName.set(s.name, toEntry(s));
+            // ...then tenant skills shadow them by name.
+            if (allowTenantSkills) {
+                for (const entry of await config.store.listCatalog({ tenantId })) {
+                    if (assignedSet.has(entry.name))
+                        byName.set(entry.name, entry);
+                }
+            }
+            return [...byName.values()];
+        },
+        async loadBody({ tenantId, name, version }) {
+            // Tenant skill of this name+version shadows the built-in.
+            const tenantSkill = await config.store.findVersion({ tenantId, name, version });
+            if (tenantSkill)
+                return tenantSkill;
+            // Resolved regardless of status, matching `findVersion`: a run pinned to a version that has since
+            // been archived must keep working. Only *discovery* hides it.
+            const builtIn = builtInByName.get(name);
+            if (builtIn && builtIn.version === version)
+                return builtIn;
+            throw new AgentPlatformError({
+                code: "not_found",
+                message: `Skill ${name}@${version} not found`,
+                retryable: false,
+            });
+        },
+    };
+};
+/**
+ * Per-run skill loader: loads a body on demand, enforces `maxLoadedPerRun`, and records every load
+ * so the run's manifest of skill versions is complete and auditable. Loading the same skill twice
+ * is idempotent and does not count against the limit again.
+ */
+export const createRunSkillTracker = (config) => {
+    const max = config.maxLoadedPerRun ?? SKILL_LIMITS.maxLoadedPerRun;
+    const clock = config.clock ?? (() => new Date().toISOString());
+    const byRun = new Map();
+    const runLog = (runId) => {
+        let m = byRun.get(runId);
+        if (!m)
+            byRun.set(runId, (m = new Map()));
+        return m;
+    };
+    return {
+        async load(input) {
+            const log = runLog(input.runId);
+            const already = log.get(input.name);
+            const body = await config.resolver.loadBody({
+                tenantId: input.tenantId,
+                name: input.name,
+                version: input.version,
+            });
+            if (!already) {
+                if (log.size >= max)
+                    throw invalid(`Run ${input.runId} has already loaded the maximum ${max} skills`);
+                log.set(input.name, { name: body.name, version: body.version, source: body.source, loadedAt: clock() });
+            }
+            return body;
+        },
+        /** The skill versions loaded during a run — recorded on the run per the acceptance criteria. */
+        recorded(runId) {
+            return [...runLog(runId).values()];
+        },
+    };
+};
+//# sourceMappingURL=resolver.js.map

package/dist/teams/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Teams — REQ-037 (#186).
+ *
+ * ## A team compiles to a flow
+ *
+ * There is no team interpreter. `compileTeam` turns a `TeamDefinition` into a `FlowDefinition`, and the flow
+ * interpreter runs it. That is the whole design, and it is what makes #186's acceptance criteria properties rather
+ * than features to add:
+ *
+ * - **AC-2, "the difference is a property of the team rather than two code paths"** — both processes compile to a
+ *   flow. `sequential` produces a chain of agent steps; `manager-led` produces one agent step whose tools include
+ *   a delegation tool. The interpreter does not know which it is running.
+ * - **AC-4, budgets compose** — a team's budget *is* the compiled flow's budget, checked by the same code that
+ *   checks a flow's. A member cannot exceed the team's remaining budget because the check is on the execution's
+ *   spend, and there is one execution.
+ * - **AC-5, bounded recursion** — `maxDepth` on the compiled flow, enforced by the interpreter. A → B → A
+ *   terminates for the same reason a nested subflow does.
+ * - **AC-6, one run identity** — one `FlowExecution`, so one `runId`. Each member's steps are attributable inside
+ *   it through `StepRecord.member`.
+ * - **AC-7, HITL inside a team** — a member's question parks the execution exactly as a flow's checkpoint does,
+ *   because it *is* the same mechanism.
+ * - **AC-8, a member failing is modelled** — `onFailure` per step, chosen by the team.
+ *
+ * Writing a second interpreter would have meant a second answer to each of those, and the second answer is the one
+ * that gets a fix late.
+ *
+ * ## Manager-led is one agent turn with a delegation tool
+ *
+ * The obvious design is a loop: ask the manager who is next, run them, ask again. The better one is to give the
+ * manager a *tool* that runs a member, and let the engine's existing turn loop do the iterating — because #186
+ * AC-3 asks that "delegation is a tool call, so it inherits authorization, approval, idempotency and accounting
+ * unchanged", and the way to inherit those unchanged is to be a tool call rather than to resemble one.
+ *
+ * So a delegation is a real entry in the registry. It is authorised like any tool, its result is recorded like any
+ * tool's, its cost lands on the run like any tool's, and a retry deduplicates like any tool's.
+ */
+import type { FlowDefinition, TeamDefinition, TeamMember } from "../flows/index.js";
+export declare const DEFAULT_DELEGATION_DEPTH = 3;
+/**
+ * The tool a manager calls to hand work to a member.
+ *
+ * Named once, here, because three things have to agree on it: the compiled flow that puts it in the manager's
+ * tool set, the registry entry that implements it, and the guard that stops a member reaching it recursively.
+ */
+export declare const DELEGATE_TOOL = "delegate_to_member";
+export type TeamCompileProblem = {
+    readonly team: string;
+    readonly problem: string;
+};
+/**
+ * Is this team runnable at all?
+ *
+ * Checked before compiling rather than discovered while running, because every one of these produces a flow that
+ * fails at a step rather than a definition that fails to load — and a definition that only fails once someone
+ * triggers it is a definition that fails in front of a customer.
+ */
+export declare const validateTeam: (team: TeamDefinition) => readonly TeamCompileProblem[];
+/**
+ * Turn a team into the flow that runs it.
+ *
+ * Pure, so a team's shape can be asserted without executing anything — which matters more than usual here,
+ * because the interesting claims are about the *graph* ("a member cannot outspend the team", "delegation is a
+ * tool") rather than about behaviour at a step.
+ */
+export declare const compileTeam: (team: TeamDefinition) => FlowDefinition;
+/**
+ * What the manager is told about its team.
+ *
+ * Generated from the definition rather than written by hand, because a manager whose instructions list a member
+ * the team no longer has will delegate to it and get a refusal it cannot act on — and that is a definition and a
+ * prompt disagreeing, which nothing would catch.
+ */
+export declare const managerInstructions: (team: TeamDefinition) => string;
+/**
+ * The tools a member may use.
+ *
+ * An **intersection**, never a union — #186 AC-3's second half: "a delegated agent cannot reach a tool the
+ * delegating one could not." A member's `tools` narrows; it cannot widen. Enforced where the set is built rather
+ * than checked afterwards, because a check afterwards is a check somebody can forget to call.
+ *
+ * A member that names a tool the delegating context does not have gets it silently dropped rather than an error:
+ * the team is still runnable, and the alternative is a whole team refusing to start because one member's list
+ * mentions something a particular caller's role happens to exclude — which would make a team's usability depend
+ * on who triggered it.
+ */
+export declare const memberTools: (input: {
+    readonly member: TeamMember;
+    /** What the delegating context can reach. The ceiling. */
+    readonly available: readonly string[];
+}) => readonly string[];
+/** The brief a team execution starts from, under the key the compiled prompts read. */
+export declare const teamBrief: (brief: string) => Readonly<Record<string, unknown>>;
+//# sourceMappingURL=index.d.ts.map