stageflow 0.36.0 → 0.39.0

package/dist/agents/communications/supervisor.d.ts

@@ -0,0 +1,36 @@
+import type { AgentService } from "../service.js";
+import type { ListenerConnection } from "./inbound.js";
+import type { ChannelListener, ListenerDeps, ListenerState } from "./listener.js";
+import type { AgentInboundMessage } from "./port.js";
+export type ListenerFactory = (connection: ListenerConnection, deps: ListenerDeps) => ChannelListener | undefined;
+/** Listeners the Host can hold open itself. Other providers (Slack, Telegram) stay on webhooks. */
+export declare const DEFAULT_FACTORIES: Record<string, ListenerFactory>;
+/**
+ * Keeps one listener per connection that an enabled agent answers on: starts it when the agent is enabled or
+ * linked, restarts it when the connection's settings change, stops it when no enabled agent uses it.
+ * `reconcile` is cheap and idempotent, so it runs on every agent change and on a timer.
+ */
+export declare class ChannelSupervisor {
+    private readonly options;
+    private readonly running;
+    private chain;
+    private timer;
+    private stopped;
+    private readonly warned;
+    constructor(options: {
+        service: Pick<AgentService, "list" | "onChange">;
+        projectRoot: string;
+        resolve: (connectionId: string) => ListenerConnection | undefined;
+        deliver: (message: AgentInboundMessage) => Promise<unknown>;
+        log: (message: string) => void;
+        factories?: Record<string, ListenerFactory>;
+        intervalMs?: number;
+    });
+    /** Start following agents: listeners for what is linked now, and again after every change. */
+    start(): void;
+    reconcile(): Promise<void>;
+    private run;
+    /** The state of the listener on a connection, or undefined when none runs (webhook providers, no enabled agent). */
+    status(connectionId: string): ListenerState | undefined;
+    stop(): Promise<void>;
+}

package/dist/agents/communications/supervisor.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+import { channelIdentity } from "./identity.js";
+import { createAgentMailListener, sdkAgentMailTransport } from "./agentmailListener.js";
+import { createIMessageListener, sdkIMessageTransport } from "./imessageListener.js";
+/** Listeners the Host can hold open itself. Other providers (Slack, Telegram) stay on webhooks. */
+export const DEFAULT_FACTORIES = {
+    agentmail: (connection, deps) => {
+        const config = connection.config;
+        const apiKey = connection.secrets.apiKey;
+        if (!config.inbox || !apiKey)
+            return undefined;
+        return createAgentMailListener({ connectionId: connection.id, inbox: config.inbox }, sdkAgentMailTransport({ apiKey, region: config.region ?? "us", inbox: config.inbox }), deps);
+    },
+    imessage: (connection, deps) => {
+        const secrets = connection.credential?.secrets;
+        if (!secrets?.projectId || !secrets.projectSecret)
+            return undefined;
+        return createIMessageListener({ connectionId: connection.id }, sdkIMessageTransport({ projectId: secrets.projectId, projectSecret: secrets.projectSecret }), deps);
+    },
+};
+const fingerprintOf = (connection) => createHash("sha256").update(JSON.stringify([connection.provider, connection.config, connection.secrets, connection.credential?.secrets])).digest("hex");
+/**
+ * Keeps one listener per connection that an enabled agent answers on: starts it when the agent is enabled or
+ * linked, restarts it when the connection's settings change, stops it when no enabled agent uses it.
+ * `reconcile` is cheap and idempotent, so it runs on every agent change and on a timer.
+ */
+export class ChannelSupervisor {
+    options;
+    running = new Map();
+    chain = Promise.resolve();
+    timer;
+    stopped = false;
+    warned = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    /** Start following agents: listeners for what is linked now, and again after every change. */
+    start() {
+        this.options.service.onChange(() => void this.reconcile());
+        void this.reconcile();
+        this.timer = setInterval(() => void this.reconcile(), this.options.intervalMs ?? 60_000);
+        this.timer.unref?.();
+    }
+    reconcile() {
+        this.chain = this.chain.then(() => this.run()).catch((error) => this.options.log(`channel listeners: ${error instanceof Error ? error.message : String(error)}`));
+        return this.chain;
+    }
+    async run() {
+        if (this.stopped)
+            return;
+        const agents = await this.options.service.list(this.options.projectRoot);
+        const wanted = new Set(agents.filter((agent) => agent.enabled && agent.channelConnection).map((agent) => agent.channelConnection));
+        for (const [id, entry] of [...this.running]) {
+            const connection = wanted.has(id) ? this.options.resolve(id) : undefined;
+            if (connection && fingerprintOf(connection) === entry.fingerprint)
+                continue;
+            await entry.listener.stop().catch(() => undefined);
+            this.running.delete(id);
+        }
+        for (const id of [...wanted].sort()) {
+            if (this.running.has(id) || this.stopped)
+                continue;
+            const connection = this.options.resolve(id);
+            const factory = connection ? (this.options.factories ?? DEFAULT_FACTORIES)[connection.provider] : undefined;
+            if (!connection || !factory)
+                continue;
+            // Two connections can point at one inbox; a second stream would deliver every message twice.
+            const identity = channelIdentity(connection);
+            const holder = [...this.running].find(([, entry]) => entry.identity === identity)?.[0];
+            if (holder) {
+                if (!this.warned.has(id))
+                    this.options.log(`channel listeners: ${id} reaches the same inbox or line as ${holder}; only ${holder} is listened to`);
+                this.warned.add(id);
+                continue;
+            }
+            this.warned.delete(id);
+            const listener = factory(connection, { onMessage: async (message) => void (await this.options.deliver(message)), log: this.options.log });
+            if (!listener)
+                continue;
+            this.running.set(id, { listener, fingerprint: fingerprintOf(connection), identity });
+            await listener.start();
+        }
+    }
+    /** The state of the listener on a connection, or undefined when none runs (webhook providers, no enabled agent). */
+    status(connectionId) {
+        return this.running.get(connectionId)?.listener.state();
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        await this.chain.catch(() => undefined);
+        await Promise.all([...this.running.values()].map((entry) => entry.listener.stop().catch(() => undefined)));
+        this.running.clear();
+    }
+}

package/dist/agents/communications/telegram.d.ts

@@ -0,0 +1,19 @@
+import type { AgentInboundMessage } from "./port.js";
+export type TelegramInboundConfig = {
+    connectionId: string;
+    secretToken?: string;
+};
+export type TelegramParseResult = {
+    ok: true;
+    message: AgentInboundMessage;
+} | {
+    ok: false;
+    code: "agent.signature_invalid" | "agent.invalid";
+};
+export declare function verifyTelegramSecret(config: TelegramInboundConfig, headerToken: string | undefined): {
+    ok: true;
+} | {
+    ok: false;
+    code: "agent.signature_invalid";
+};
+export declare function parseTelegramInbound(config: TelegramInboundConfig, payload: unknown): TelegramParseResult;

package/dist/agents/communications/telegram.js

@@ -0,0 +1,52 @@
+import { timingSafeEqual } from "node:crypto";
+export function verifyTelegramSecret(config, headerToken) {
+    if (config.secretToken === undefined)
+        return { ok: true };
+    if (headerToken === undefined)
+        return { ok: false, code: "agent.signature_invalid" };
+    const left = Buffer.from(config.secretToken);
+    const right = Buffer.from(headerToken);
+    if (left.length !== right.length || !timingSafeEqual(left, right)) {
+        return { ok: false, code: "agent.signature_invalid" };
+    }
+    return { ok: true };
+}
+export function parseTelegramInbound(config, payload) {
+    if (typeof payload !== "object" || payload === null)
+        return { ok: false, code: "agent.invalid" };
+    const message = payload.message;
+    if (typeof message !== "object" || message === null)
+        return { ok: false, code: "agent.invalid" };
+    const record = message;
+    const text = typeof record.text === "string" ? record.text.trim() : "";
+    if (text.length === 0)
+        return { ok: false, code: "agent.invalid" };
+    const chat = record.chat;
+    if (typeof chat !== "object" || chat === null)
+        return { ok: false, code: "agent.invalid" };
+    const chatId = chat.id;
+    if (typeof chatId !== "number" && typeof chatId !== "string") {
+        return { ok: false, code: "agent.invalid" };
+    }
+    const messageId = record.message_id;
+    if (typeof messageId !== "number" || !Number.isFinite(messageId)) {
+        return { ok: false, code: "agent.invalid" };
+    }
+    const from = record.from;
+    const fromLabel = typeof from === "object" && from !== null && typeof from.username === "string"
+        ? from.username
+        : undefined;
+    const threadId = String(chatId);
+    return {
+        ok: true,
+        message: {
+            provider: "telegram",
+            connectionId: config.connectionId,
+            eventId: `telegram:${messageId}:${threadId}`,
+            threadId,
+            replyTo: threadId,
+            text,
+            ...(fromLabel !== undefined ? { from: fromLabel } : {}),
+        },
+    };
+}

package/dist/agents/definitionSummary.d.ts

@@ -0,0 +1,13 @@
+import { type AgentDefinition } from "../config/loadAgent.js";
+export type SummaryLine = {
+    label: string;
+    value: string;
+};
+/**
+ * Best-effort view of a possibly incomplete draft with schema defaults
+ * applied, so a partial draft can still be described. Required strings that
+ * are missing become empty; everything else gets its default.
+ */
+export declare function withDefaults(draft: Record<string, unknown>): AgentDefinition;
+/** One line per section that differs between two drafts, describing the new value. */
+export declare function describeChanges(before: Record<string, unknown>, after: Record<string, unknown>): SummaryLine[];

package/dist/agents/definitionSummary.js

@@ -0,0 +1,91 @@
+import { agentDefinitionSchema, BUILTIN_TOOL_GROUPS } from "../config/loadAgent.js";
+/**
+ * Best-effort view of a possibly incomplete draft with schema defaults
+ * applied, so a partial draft can still be described. Required strings that
+ * are missing become empty; everything else gets its default.
+ */
+export function withDefaults(draft) {
+    const lenient = { id: "draft", name: "draft", instructions: "draft", ...draft };
+    const parsed = agentDefinitionSchema.safeParse(lenient);
+    if (parsed.success)
+        return parsed.data;
+    // Fall back section by section so one bad field doesn't hide the rest.
+    const base = agentDefinitionSchema.parse({ id: "draft", name: "draft", instructions: "draft" });
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(draft)) {
+        const attempt = agentDefinitionSchema.safeParse({ ...base, [key]: value });
+        if (attempt.success)
+            merged[key] = attempt.data[key];
+    }
+    return merged;
+}
+function list(items, empty) {
+    return items.length > 0 ? items.join(", ") : empty;
+}
+const SECTIONS = [
+    {
+        label: "Identity",
+        keys: ["id", "name", "description", "greeting"],
+        describe: (d) => [d.name, d.id].filter(Boolean).join(" · "),
+    },
+    {
+        label: "Instructions",
+        keys: ["instructions", "project_context"],
+        describe: (d) => {
+            const lines = d.instructions.split("\n").filter((line) => line.trim()).length;
+            return `${lines} line${lines === 1 ? "" : "s"}${d.project_context ? " · reads project context" : ""}`;
+        },
+    },
+    {
+        label: "Model",
+        keys: ["model"],
+        describe: (d) => `${d.model.id ?? "project default"} · ${d.model.backend === "claude" ? "Claude" : "Pi"} · ${d.model.thinking} thinking`,
+    },
+    {
+        label: "Tools",
+        keys: ["tools"],
+        describe: (d) => list([
+            ...d.tools.builtin,
+            ...d.tools.builtin_tools.filter((tool) => !d.tools.builtin.some((group) => BUILTIN_TOOL_GROUPS[group].includes(tool))),
+            ...Object.entries(d.tools.mcp).map(([server, tools]) => `${server} (${tools.includes("*") ? "all" : tools.join(", ")})`),
+            ...d.tools.skills.map((skill) => `skill ${skill}`),
+            ...(d.tools.browser ? ["browser"] : []),
+            ...d.tools.stageflow.groups.map((group) => `stageflow ${group}`),
+            ...(d.tools.stageflow.tools.length > 0 ? [`stageflow ${d.tools.stageflow.tools.join(", ")}`] : []),
+        ], "none"),
+    },
+    {
+        label: "Approvals",
+        keys: ["approvals"],
+        describe: (d) => d.approvals.ask_first.length > 0
+            ? `asks before ${d.approvals.ask_first.join(", ")}`
+            : "nothing asks first",
+    },
+    { label: "Sub-agents", keys: ["sub_agents", "sub_agent_depth"], describe: (d) => list(d.sub_agents, "none") },
+    {
+        label: "Guardrails",
+        keys: ["guardrails", "evals"],
+        describe: (d) => `${d.guardrails.block_patterns.length} block pattern${d.guardrails.block_patterns.length === 1 ? "" : "s"}`,
+    },
+    {
+        label: "Capture",
+        keys: ["observability"],
+        describe: (d) => ({ off: "off", metadata: "timing and metadata only", full: "full content, secrets masked" })[d.observability.capture],
+    },
+    {
+        label: "Channels",
+        keys: ["channel", "schedule"],
+        describe: (d) => list([...(d.channel ? [`${d.channel.connection_id} (${d.channel.allow_from.length === 0 ? "nobody allowed" : d.channel.allow_from.join(", ")})`] : []), ...(d.schedule ? [`schedule ${d.schedule.cron}`] : [])], "console only"),
+    },
+    {
+        label: "Limits",
+        keys: ["limits"],
+        describe: (d) => `${d.limits.always_on ? "always on" : `${d.limits.session_minutes} min · ${d.limits.max_turns} turns`} · ${d.limits.cost_usd === null ? "no cost cap" : `$${d.limits.cost_usd}${d.limits.always_on ? " per day" : ""}`}`,
+    },
+];
+/** One line per section that differs between two drafts, describing the new value. */
+export function describeChanges(before, after) {
+    const a = withDefaults(before);
+    const b = withDefaults(after);
+    return SECTIONS.filter((section) => section.keys.some((key) => JSON.stringify(a[key] ?? null) !== JSON.stringify(b[key] ?? null))).map((section) => ({ label: section.label, value: section.describe(b) }));
+}

package/dist/agents/delegate.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition } from "../config/loadAgent.js";
+/** May `caller` (at nesting `depth`, 0 = top-level session) call `calleeId`? Throws when it may not. */
+export declare function assertDelegateAllowed(caller: Pick<AgentDefinition, "sub_agents" | "sub_agent_depth">, calleeId: string, depth: number): void;

package/dist/agents/delegate.js

@@ -0,0 +1,8 @@
+import { AgentError } from "./errors.js";
+/** May `caller` (at nesting `depth`, 0 = top-level session) call `calleeId`? Throws when it may not. */
+export function assertDelegateAllowed(caller, calleeId, depth) {
+    if (!caller.sub_agents.includes(calleeId))
+        throw new AgentError("agent.delegate_not_allowed");
+    if (depth >= caller.sub_agent_depth)
+        throw new AgentError("agent.delegate_depth_exceeded");
+}

package/dist/agents/errors.d.ts

@@ -0,0 +1,10 @@
+import type { AgentIssue } from "../config/loadAgent.js";
+export type AgentErrorCode = "agent.invalid" | "agent.not_found" | "agent.exists" | "agent.archived" | "agent.disabled" | "agent.conflict" | "agent.revision_not_found" | "agent.session_not_found" | "agent.session_busy" | "agent.tool_not_granted" | "agent.approval_not_required" | "agent.approval_not_pending" | "agent.approval_expired" | "agent.approval_forbidden" | "agent.unbound" | "agent.sender_not_allowed" | "agent.outbound_unknown" | "agent.trace_metadata_body" | "agent.guardrail_blocked" | "agent.delegate_not_allowed" | "agent.delegate_depth_exceeded" | "agent.sandbox_unavailable" | "agent.limit_reached" | "agent.model_timeout" | "agent.backend_unavailable" | "agent.approval_denied";
+/** Domain failure with a stable code; the HTTP, CLI and MCP layers map it, they don't parse messages. */
+export declare class AgentError extends Error {
+    readonly code: AgentErrorCode;
+    readonly issues: AgentIssue[];
+    constructor(code: AgentErrorCode, message?: string, issues?: AgentIssue[]);
+    get httpStatus(): number;
+}
+export declare function isAgentError(error: unknown): error is AgentError;

package/dist/agents/errors.js

@@ -0,0 +1,32 @@
+const STATUS = {
+    "agent.invalid": 422,
+    "agent.not_found": 404,
+    "agent.revision_not_found": 404,
+    "agent.session_not_found": 404,
+    "agent.exists": 409,
+    "agent.archived": 409,
+    "agent.disabled": 409,
+    "agent.conflict": 409,
+    "agent.session_busy": 409,
+    "agent.limit_reached": 409,
+    "agent.model_timeout": 504,
+    "agent.approval_forbidden": 403,
+    "agent.sender_not_allowed": 403,
+};
+/** Domain failure with a stable code; the HTTP, CLI and MCP layers map it, they don't parse messages. */
+export class AgentError extends Error {
+    code;
+    issues;
+    constructor(code, message, issues = []) {
+        super(message ?? code);
+        this.code = code;
+        this.issues = issues;
+        this.name = "AgentError";
+    }
+    get httpStatus() {
+        return STATUS[this.code] ?? 400;
+    }
+}
+export function isAgentError(error) {
+    return error instanceof AgentError;
+}

package/dist/agents/guardrails.d.ts

@@ -0,0 +1,24 @@
+import type { AgentGuardrails } from "../config/loadAgent.js";
+export type GuardrailResult = {
+    ok: true;
+} | {
+    ok: false;
+    pattern: string;
+};
+/** Block patterns are validated as regular expressions when the definition is parsed. */
+export declare function checkGuardrails(guardrails: AgentGuardrails, text: string): GuardrailResult;
+/**
+ * The one path model output takes to a person. Without block patterns, deltas go straight through. With them, a
+ * pattern can match text that has not been written yet, so deltas are held and released only once the finished reply
+ * (and everything held) has passed the check; a blocked reply is never streamed. The cost is that guarded agents show
+ * their reply at the end instead of word by word.
+ */
+export type GuardedStream = {
+    /** Give this to the model runtime. */
+    push(delta: string): void;
+    /** The check on the finished reply passed: let held text out. Returns the verdict; nothing is released when it fails. */
+    release(finalText: string): GuardrailResult;
+    /** The turn ended without a reply to show: drop what was held. */
+    discard(): void;
+};
+export declare function guardedStream(guardrails: AgentGuardrails, forward: ((text: string) => void) | undefined): GuardedStream;

package/dist/agents/guardrails.js

@@ -0,0 +1,39 @@
+/** Block patterns are validated as regular expressions when the definition is parsed. */
+export function checkGuardrails(guardrails, text) {
+    for (const pattern of guardrails.block_patterns) {
+        if (new RegExp(pattern).test(text))
+            return { ok: false, pattern };
+    }
+    return { ok: true };
+}
+export function guardedStream(guardrails, forward) {
+    if (guardrails.block_patterns.length === 0) {
+        return { push: (delta) => forward?.(delta), release: () => ({ ok: true }), discard: () => undefined };
+    }
+    let held = [];
+    return {
+        push: (delta) => {
+            held.push(delta);
+        },
+        release(finalText) {
+            const verdict = checkGuardrails(guardrails, finalText);
+            if (!verdict.ok) {
+                held = [];
+                return verdict;
+            }
+            const streamed = checkGuardrails(guardrails, held.join(""));
+            if (!streamed.ok) {
+                held = [];
+                return streamed;
+            }
+            const out = held;
+            held = [];
+            for (const delta of out)
+                forward?.(delta);
+            return { ok: true };
+        },
+        discard() {
+            held = [];
+        },
+    };
+}

package/dist/agents/historyFit.d.ts

@@ -0,0 +1,10 @@
+import type { AgentDefinition } from "../config/loadAgent.js";
+import type { ConversationMessage } from "./runtime/types.js";
+/** Characters of replayed history a restarted session is given (about 15k tokens). */
+export declare const HISTORY_CHAR_BUDGET = 60000;
+/**
+ * Apply `limits.long_context` when a transcript is replayed into a new model
+ * session: `truncate` drops the oldest messages; `summarize` condenses them to
+ * one line each so the thread is still visible. The newest message is always kept.
+ */
+export declare function fitHistory(messages: readonly ConversationMessage[], policy: AgentDefinition["limits"]["long_context"], budget?: number): ConversationMessage[];

package/dist/agents/historyFit.js

@@ -0,0 +1,26 @@
+/** Characters of replayed history a restarted session is given (about 15k tokens). */
+export const HISTORY_CHAR_BUDGET = 60_000;
+/**
+ * Apply `limits.long_context` when a transcript is replayed into a new model
+ * session: `truncate` drops the oldest messages; `summarize` condenses them to
+ * one line each so the thread is still visible. The newest message is always kept.
+ */
+export function fitHistory(messages, policy, budget = HISTORY_CHAR_BUDGET) {
+    const total = messages.reduce((sum, m) => sum + m.text.length, 0);
+    if (total <= budget || messages.length <= 1)
+        return [...messages];
+    const kept = [];
+    let used = 0;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messages[i];
+        if (kept.length > 0 && used + message.text.length > budget)
+            break;
+        kept.unshift(message);
+        used += message.text.length;
+    }
+    const dropped = messages.slice(0, messages.length - kept.length);
+    if (policy === "truncate" || dropped.length === 0)
+        return kept;
+    const digest = dropped.map((m) => `- ${m.role}: ${m.text.replace(/\s+/g, " ").trim().slice(0, 160)}`).join("\n");
+    return [{ role: "assistant", text: `Earlier in this conversation (condensed):\n${digest}` }, ...kept];
+}

package/dist/agents/hostContext.d.ts

@@ -0,0 +1,54 @@
+import type Database from "better-sqlite3";
+import type { ChannelService } from "../channels/service.js";
+import { AgentInboundRouter } from "./communications/inbound.js";
+import { ReplyDelivery } from "./communications/delivery.js";
+import { ChannelSupervisor } from "./communications/supervisor.js";
+import { AgentChatController } from "./chatTurn.js";
+import { type OtlpSink } from "./otlpSink.js";
+import type { ContactInfo } from "../channels/types.js";
+import type { McpToolDeps } from "../mcp/deps.js";
+import { AgentService, type AgentEnvironment } from "./service.js";
+import type { ConversationBackend } from "./sessions.js";
+import { PublicWebChat } from "./webChat/publicChat.js";
+export type AgentHostContext = {
+    service: AgentService;
+    inbound: AgentInboundRouter;
+    publicChat: PublicWebChat;
+    chat: AgentChatController;
+    backend: ConversationBackend;
+    /** Streams held open to AgentMail and iMessage; absent unless the Host listens (not in tests). */
+    channelListeners?: ChannelSupervisor;
+    /** Replies to people on channels: retries, resend, mark delivered. */
+    delivery: ReplyDelivery;
+    /** How people reach a connection (the number to text), cached for a minute. */
+    channelContact(connectionId: string): Promise<{
+        provider: string;
+        contact: ContactInfo;
+    } | undefined>;
+    /** Stop what the Host started for agents (listeners). */
+    stop(): Promise<void>;
+};
+/** Read-only lookups the editor warnings use: `.mcp.json`, skills, and channel connections. */
+export declare function createAgentEnvironment(options: {
+    agentDir: string;
+    cwd: string;
+    channels?: Pick<ChannelService, "list">;
+}): AgentEnvironment;
+/**
+ * Agent runtime for one Host. Agent state shares the Host's SQLite connection
+ * (migration 013). Turns left running by a previous process are failed here,
+ * since nothing can resume them.
+ */
+export declare function createAgentHostContext(options: {
+    cwd: string;
+    agentDir: string;
+    connection: Database.Database;
+    channels?: Pick<ChannelService, "list">;
+    backend?: ConversationBackend;
+    environment?: AgentEnvironment;
+    otlpSink?: OtlpSink | undefined;
+    /** Host services the Stageflow tools need; agent services are added here. Without it agents get no Stageflow tools. */
+    /** Hold streams open to AgentMail and iMessage for agents linked to them. Only a running Host does this. */
+    listenOnChannels?: boolean;
+    toolkitDeps?: Pick<McpToolDeps, "manager" | "store" | "agentDir" | "providerAuthContext" | "projectRoot" | "providerBoot">;
+}): AgentHostContext;