@retinue/agentkit 0.1.0

package/dist/teams/index.js

@@ -0,0 +1,207 @@
+/**
+ * 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 { AgentPlatformError } from "../core/errors.js";
+import { DEFAULT_MAX_DEPTH } from "../flows/index.js";
+export 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 const DELEGATE_TOOL = "delegate_to_member";
+/**
+ * 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 const validateTeam = (team) => {
+    const problems = [];
+    const at = (problem) => problems.push({ team: team.id, problem });
+    if (team.members.length === 0)
+        at("has no members");
+    const names = new Set();
+    for (const member of team.members) {
+        if (member.name.trim() === "")
+            at("has a member with no name");
+        if (names.has(member.name))
+            at(`has two members named "${member.name}" — a delegation could not say which`);
+        names.add(member.name);
+    }
+    if (team.process === "manager-led") {
+        if (team.manager === undefined)
+            at("is manager-led with no manager named");
+        else if (!names.has(team.manager))
+            at(`names "${team.manager}" as manager, which is not one of its members`);
+    }
+    else if (team.manager !== undefined) {
+        // A sequential team with a manager is ambiguous: does the manager run first, last, or not at all? Refusing is
+        // better than picking one and being right a third of the time.
+        at("is sequential but names a manager — a sequential team has no manager to obey");
+    }
+    if (team.budget.maxSteps < team.members.length && team.process === "sequential") {
+        // A sequential team whose budget cannot reach its last member is a team that always fails at the same place,
+        // and the failure would read as a runtime problem rather than a definition one.
+        at(`has ${team.members.length} members and a budget of ${team.budget.maxSteps} steps, so its last member can never run`);
+    }
+    return problems;
+};
+/**
+ * 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 const compileTeam = (team) => {
+    const problems = validateTeam(team);
+    if (problems.length > 0) {
+        throw new AgentPlatformError({
+            code: "invalid_input",
+            message: `team ${team.id} cannot be compiled: ${problems.map((p) => p.problem).join("; ")}`,
+            retryable: false,
+        });
+    }
+    const steps = team.process === "sequential" ? sequentialSteps(team) : managerLedSteps(team);
+    return {
+        id: `team:${team.id}`,
+        version: team.version,
+        name: team.name,
+        description: `Compiled from team ${team.id} (${team.process})`,
+        steps,
+        start: steps[0].name,
+        // The team's budget *is* the flow's. One budget, checked by one piece of code — so "a member cannot exceed
+        // the team's remaining budget" needs no separate enforcement.
+        budget: team.budget,
+        maxDepth: team.maxDelegationDepth ?? DEFAULT_DELEGATION_DEPTH,
+    };
+};
+/**
+ * Each member in turn, each reading the previous one's output.
+ *
+ * `assignTo` is the member's name, so a later member's prompt can reference `{{$.researcher}}` — which is how one
+ * agent's output becomes another's input "inside a single unit of work", and it is readable in the stored state
+ * rather than threaded through a closure nobody can inspect.
+ */
+const sequentialSteps = (team) => {
+    const steps = team.members.map((member, index) => {
+        const next = index + 1 < team.members.length ? team.members[index + 1].name : "team:done";
+        return {
+            name: member.name,
+            kind: "agent",
+            agentId: member.agentId,
+            ...(member.instructions === undefined ? {} : { instructions: member.instructions }),
+            /**
+             * The task, plus what came before.
+             *
+             * The first member sees the team's brief; every later one sees the brief *and* the previous member's output.
+             * Passing only the previous output would lose the original request by the third member, which is the classic
+             * way a chain of agents drifts off the question.
+             */
+            prompt: index === 0
+                ? "{{$.brief}}"
+                : `{{$.brief}}\n\nWhat ${team.members[index - 1].name} produced:\n{{$.${team.members[index - 1].name}}}`,
+            assignTo: member.name,
+            next,
+        };
+    });
+    steps.push({ name: "team:done", kind: "done" });
+    return steps;
+};
+/**
+ * One step: the manager, with a delegation tool.
+ *
+ * The engine's own turn loop does the iterating, bounded by the agent's execution limits — so there is no
+ * hand-written loop here to get wrong, and a delegation is a tool call rather than something shaped like one.
+ */
+const managerLedSteps = (team) => [
+    {
+        name: team.manager,
+        kind: "agent",
+        agentId: team.members.find((m) => m.name === team.manager).agentId,
+        instructions: managerInstructions(team),
+        prompt: "{{$.brief}}",
+        assignTo: "result",
+        next: "team:done",
+    },
+    { name: "team:done", kind: "done" },
+];
+/**
+ * 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 const managerInstructions = (team) => {
+    const others = team.members.filter((member) => member.name !== team.manager);
+    const roster = others.map((member) => `- ${member.name}: ${member.instructions ?? "no stated speciality"}`).join("\n");
+    return [
+        `You lead a team. Delegate work with the ${DELEGATE_TOOL} tool; do not do a member's work yourself when one of them is better placed.`,
+        "",
+        "Your team:",
+        roster,
+        "",
+        `Delegate one task at a time and read the result before deciding what is next. When the work is done, answer directly — do not delegate again to confirm.`,
+    ].join("\n");
+};
+/**
+ * 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 const memberTools = (input) => {
+    const available = new Set(input.available);
+    if (input.member.tools === undefined) {
+        // No narrowing stated: the member gets what the team has, minus the delegation tool — a member that could
+        // delegate would be a manager, and a member delegating back to the manager is the A → B → A this bounds.
+        return [...available].filter((tool) => tool !== DELEGATE_TOOL);
+    }
+    return input.member.tools.filter((tool) => available.has(tool) && tool !== DELEGATE_TOOL);
+};
+/** The brief a team execution starts from, under the key the compiled prompts read. */
+export const teamBrief = (brief) => ({ brief });
+//# sourceMappingURL=index.js.map

package/dist/telemetry/index.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The telemetry port — REQ-033 (#143).
+ *
+ * A run crosses the API host, the queue and a worker. Without a correlated view, diagnosing a production issue
+ * means guessing, so this exists to make one user request one trace.
+ *
+ * **Ours, not a vendor's.** The port is our own types; `adapters/otel` binds them to OpenTelemetry. Nothing in
+ * `src/` outside that adapter imports an OTel package, and a boundary rule (R11) makes that a build failure
+ * rather than a convention — the same treatment R3 gives the AI SDK. "Vendor-neutral" is only true if it is
+ * enforced: a single convenience import of `@opentelemetry/api` in a hot path is how a platform acquires a
+ * vendor, and it is invisible in review.
+ *
+ * **Shaped for W3C trace context, because that is the interop surface.** The port's identifiers are trace ids,
+ * span ids and a `traceparent` string, which is what any collector understands. A bespoke correlation id would
+ * work exactly as well until a customer wanted their own tooling to see it.
+ *
+ * **Absence is a no-op, not a branch.** `NOOP_TELEMETRY` means no call site needs `if (telemetry)`, so an
+ * unconfigured deployment loses observability and nothing else. Optional-and-checked would eventually be
+ * checked in nineteen places and forgotten in the twentieth.
+ */
+export * from "./trace-context.js";
+export * from "./log-events.js";
+export * from "./redaction.js";
+export * from "./spans.js";
+export * from "./metrics.js";
+export * from "./noop.js";
+export * from "./instrument.js";
+import type { LogEvent } from "./log-events.js";
+import type { TraceFlags } from "./trace-context.js";
+/**
+ * The identifiers on every log line and every span — AC-4.
+ *
+ * Every field is an id. That is the point: this type is what a caller is *allowed* to correlate on, and it
+ * contains no room for content. A telemetry context that carried a `message` or a `prompt` would be the
+ * redaction hole, and it would be added by someone who needed one line of context in one incident.
+ */
+export type TelemetryContext = {
+    readonly tenantId: string;
+    readonly conversationId?: string;
+    readonly runId?: string;
+    readonly principalId?: string;
+    /** The inbound request, so a trace can be tied back to an access log entry. */
+    readonly requestId?: string;
+};
+export declare const SPAN_KINDS: readonly ["server", "client", "producer", "consumer", "internal"];
+export type SpanKind = (typeof SPAN_KINDS)[number];
+/**
+ * A span attribute value.
+ *
+ * Primitives only, and deliberately not `unknown`. A nested object is where content hides: `{ input: {...} }`
+ * on a tool span is one keystroke from being the whole tool input, and no reviewer would notice. A caller that
+ * genuinely needs structure has to name each field, which is exactly the friction that keeps prompts out.
+ */
+export type AttributeValue = string | number | boolean;
+export type Attributes = Readonly<Record<string, AttributeValue>>;
+export type SpanStatus = "unset" | "ok" | "error";
+export interface Span {
+    /** The span's own context, for propagation into a job payload or an outbound header. */
+    readonly context: SpanContext;
+    setAttributes(attributes: Attributes): void;
+    /**
+     * Record a failure on the span.
+     *
+     * Takes a **code and message**, not an error object. An error's `stack` and `cause` chain routinely carry a
+     * URL with a token in it or the argument that caused the throw — #131 found exactly that, a service-role key
+     * echoed into an error message and therefore into logs. So the span gets the classified code and a message
+     * the caller has taken responsibility for, and the object stays out.
+     */
+    recordError(input: {
+        readonly code: string;
+        readonly message?: string;
+    }): void;
+    setStatus(status: SpanStatus): void;
+    end(): void;
+}
+export type SpanContext = {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly traceFlags: TraceFlags;
+};
+export type SpanOptions = {
+    readonly kind?: SpanKind;
+    readonly attributes?: Attributes;
+    /**
+     * The parent, as a `traceparent` string.
+     *
+     * A string rather than a span object, because the parent usually arrives *serialized* — out of a job payload
+     * or an HTTP header — and a port that took a live span would force every producer to keep one alive across a
+     * process boundary, which is the one thing it cannot do.
+     */
+    readonly parent?: string;
+};
+export interface Tracer {
+    startSpan(name: string, options?: SpanOptions): Span;
+}
+/**
+ * Run `fn` inside a span, ending it on both paths and recording a failure.
+ *
+ * A helper rather than a method on the port, so an adapter cannot get the error path wrong. Every adapter
+ * getting `try/finally` right independently is a guarantee that holds until the second adapter.
+ */
+export declare const withSpan: <T>(tracer: Tracer, name: string, options: SpanOptions, fn: (span: Span) => Promise<T>) => Promise<T>;
+/**
+ * A classified code for a thrown value, and nothing else.
+ *
+ * Reads `code` when the platform's own error carries one, and otherwise reports the constructor name. Never the
+ * message: this function's whole job is to be the place that refuses to pass one through.
+ */
+export declare const errorCodeOf: (error: unknown) => string;
+export type MetricRecorder = {
+    record(value: number, attributes?: Attributes): void;
+};
+export interface Meter {
+    /** Monotonic count — requests, errors, runs. */
+    counter(name: string, options?: {
+        readonly unit?: string;
+        readonly description?: string;
+    }): MetricRecorder;
+    /** A distribution — latency, duration, wait time. Percentiles are the only useful form of these. */
+    histogram(name: string, options?: {
+        readonly unit?: string;
+        readonly description?: string;
+    }): MetricRecorder;
+    /** A point-in-time value — queue depth. Recorded, not accumulated. */
+    gauge(name: string, options?: {
+        readonly unit?: string;
+        readonly description?: string;
+    }): MetricRecorder;
+}
+export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+/**
+ * A structured log line.
+ *
+ * `event` is a **closed union of literals**, not free text — see `log-events.ts`. That is the structural half
+ * of AC-5: a caller physically cannot put a prompt in the message, because the message is not a string it
+ * controls. The redaction allowlist then handles the fields. A denylist over free-text messages would be
+ * checking every line forever and losing the one added on a Friday.
+ */
+export type LogRecord = {
+    readonly level: LogLevel;
+    readonly event: LogEvent;
+    readonly context: TelemetryContext;
+    readonly fields: Readonly<Record<string, AttributeValue>>;
+    readonly at: string;
+};
+export interface Logger {
+    log(level: LogLevel, event: LogEvent, fields?: Readonly<Record<string, unknown>>): void;
+    /** A logger bound to more context. Correlation ids are set once at a boundary, not repeated per line. */
+    child(context: Partial<TelemetryContext>): Logger;
+}
+export type Telemetry = {
+    readonly tracer: Tracer;
+    readonly meter: Meter;
+    readonly logger: Logger;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.js

@@ -0,0 +1,71 @@
+/**
+ * The telemetry port — REQ-033 (#143).
+ *
+ * A run crosses the API host, the queue and a worker. Without a correlated view, diagnosing a production issue
+ * means guessing, so this exists to make one user request one trace.
+ *
+ * **Ours, not a vendor's.** The port is our own types; `adapters/otel` binds them to OpenTelemetry. Nothing in
+ * `src/` outside that adapter imports an OTel package, and a boundary rule (R11) makes that a build failure
+ * rather than a convention — the same treatment R3 gives the AI SDK. "Vendor-neutral" is only true if it is
+ * enforced: a single convenience import of `@opentelemetry/api` in a hot path is how a platform acquires a
+ * vendor, and it is invisible in review.
+ *
+ * **Shaped for W3C trace context, because that is the interop surface.** The port's identifiers are trace ids,
+ * span ids and a `traceparent` string, which is what any collector understands. A bespoke correlation id would
+ * work exactly as well until a customer wanted their own tooling to see it.
+ *
+ * **Absence is a no-op, not a branch.** `NOOP_TELEMETRY` means no call site needs `if (telemetry)`, so an
+ * unconfigured deployment loses observability and nothing else. Optional-and-checked would eventually be
+ * checked in nineteen places and forgotten in the twentieth.
+ */
+export * from "./trace-context.js";
+export * from "./log-events.js";
+export * from "./redaction.js";
+export * from "./spans.js";
+export * from "./metrics.js";
+export * from "./noop.js";
+export * from "./instrument.js";
+export const SPAN_KINDS = ["server", "client", "producer", "consumer", "internal"];
+/**
+ * Run `fn` inside a span, ending it on both paths and recording a failure.
+ *
+ * A helper rather than a method on the port, so an adapter cannot get the error path wrong. Every adapter
+ * getting `try/finally` right independently is a guarantee that holds until the second adapter.
+ */
+export const withSpan = async (tracer, name, options, fn) => {
+    const span = tracer.startSpan(name, options);
+    try {
+        const result = await fn(span);
+        span.setStatus("ok");
+        return result;
+    }
+    catch (error) {
+        // The code only. `String(error)` here would put the message on the span, and an error message is the most
+        // common accidental carrier of content — a rejected prompt, a failing SQL statement, a signed URL.
+        span.recordError({ code: errorCodeOf(error) });
+        span.setStatus("error");
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+};
+/**
+ * A classified code for a thrown value, and nothing else.
+ *
+ * Reads `code` when the platform's own error carries one, and otherwise reports the constructor name. Never the
+ * message: this function's whole job is to be the place that refuses to pass one through.
+ */
+export const errorCodeOf = (error) => {
+    if (typeof error === "object" && error !== null) {
+        const code = error.code;
+        if (typeof code === "string" && code.length > 0 && code.length <= 64)
+            return code;
+        const name = error.constructor?.name;
+        if (typeof name === "string" && name.length > 0)
+            return name;
+    }
+    return "unknown";
+};
+export const LOG_LEVELS = ["debug", "info", "warn", "error"];
+//# sourceMappingURL=index.js.map

package/dist/telemetry/instrument.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Wiring telemetry to the boundaries — AC-1, AC-2, AC-3.
+ *
+ * The port is inert on its own. These are the wrappers that put it on the path a run actually takes, and they
+ * are **decorators over the existing seams** rather than edits inside them: `instrumentDispatcher` wraps a
+ * `JobDispatcher`, `instrumentConsumer` wraps a `JobConsumer`. Two reasons, and the second is the real one.
+ *
+ * The first is that a deployment without telemetry runs the undecorated object, so telemetry cannot be the
+ * reason a run fails.
+ *
+ * The second is that instrumentation *inside* the dispatcher would put a span around the enqueue and nothing
+ * around the wait between enqueue and claim — which is the number a user actually experiences. Wrapping both
+ * sides is what makes claim latency measurable at all.
+ */
+import type { JobDispatcher } from "../runtime/index.js";
+import type { JobConsumer } from "../worker/main.js";
+import { type RunMetrics } from "./metrics.js";
+import { type Telemetry } from "./index.js";
+/**
+ * What a job carries so the worker can continue the trace — AC-1.
+ *
+ * `traceparent` is **optional**, and that is a compatibility decision rather than laziness: jobs enqueued before
+ * this landed are already on the queue, and a worker that required the field would fail every one of them. A job
+ * without it starts a new trace, which is a missing link in one trace rather than a lost run.
+ *
+ * `enqueuedAt` rides along for the same reason claim latency cannot be measured on one side: the worker needs to
+ * know when the producer let go. Taken from the producer's clock, so the number is only as good as clock skew
+ * between the two hosts — stated because a negative claim latency in a dashboard is otherwise a mystery.
+ */
+export type TracedJob = {
+    readonly traceparent?: string;
+    readonly enqueuedAt?: string;
+};
+export type InstrumentedDispatcherDeps = {
+    readonly telemetry: Telemetry;
+    readonly metrics?: RunMetrics;
+    /** Injected so a test can pin it; also what makes claim latency assertable without waiting. */
+    readonly now?: () => number;
+};
+/**
+ * Wrap a dispatcher so the enqueue is a span and the job carries the trace forward.
+ *
+ * The traceparent goes down through `enqueueRun`, which #143 widened to accept it. The first version of this
+ * remembered the span it had just opened and let the adapter read it back — which is wrong the moment two
+ * enqueues overlap, and overlapping enqueues are the normal case, not the edge one. A racy trace link is worse
+ * than none: it attributes one tenant's run to another tenant's request.
+ */
+export declare const instrumentDispatcher: (inner: JobDispatcher, deps: InstrumentedDispatcherDeps) => JobDispatcher;
+export type InstrumentedConsumerDeps = InstrumentedDispatcherDeps & {
+    /** Which worker process this is. On a log line, so a stuck instance is identifiable. */
+    readonly workerId?: string;
+};
+/**
+ * Wrap a consumer so each job continues its producer's trace and claim latency is recorded.
+ *
+ * The handler runs *inside* the claim span, so everything the run does — model calls, tool calls, an approval
+ * wait — is a descendant of it and of the original request. That is AC-1: one user request, one trace, across
+ * three processes.
+ */
+export declare const instrumentConsumer: (inner: JobConsumer, deps: InstrumentedConsumerDeps) => JobConsumer;
+/**
+ * Time a model call — latency, outcome and the model, with no prompt anywhere near it.
+ *
+ * The attributes are the model id and the outcome. Not the prompt, not the response, not the token *contents* —
+ * the counts are on the usage ledger, which is the place designed to hold them and which is tenant-scoped.
+ */
+export declare const instrumentModelCall: <T>(deps: {
+    readonly telemetry: Telemetry;
+    readonly metrics: RunMetrics;
+    readonly now?: () => number;
+}, input: {
+    readonly tenantId: string;
+    readonly runId?: string;
+    readonly modelId: string;
+    readonly providerId?: string;
+}, call: () => Promise<T>) => Promise<T>;
+/** Time a tool call. Same shape, and the same deliberate absence of arguments and results. */
+export declare const instrumentToolCall: <T>(deps: {
+    readonly telemetry: Telemetry;
+    readonly metrics: RunMetrics;
+    readonly now?: () => number;
+}, input: {
+    readonly tenantId: string;
+    readonly runId?: string;
+    readonly toolName: string;
+}, call: () => Promise<T>) => Promise<T>;
+/**
+ * Record how long a run waited for a human.
+ *
+ * Not a wrapper, because the wait is not a function call: the run is *suspended*, the process may have exited,
+ * and the decision arrives in a different request entirely. So this is called when the decision lands, with both
+ * timestamps — the only shape that can measure a wait spanning a deploy.
+ *
+ * Often the longest span in a trace, and the one that most needs to be visibly *not* the platform's latency.
+ */
+export declare const recordApprovalWait: (deps: {
+    readonly telemetry: Telemetry;
+    readonly metrics: RunMetrics;
+}, input: {
+    readonly tenantId: string;
+    readonly runId: string;
+    readonly interactionId: string;
+    readonly requestedAt: string;
+    readonly decidedAt: string;
+    readonly decision: string;
+    readonly traceparent?: string;
+}) => void;
+//# sourceMappingURL=instrument.d.ts.map