@akira-tl/forgerelay 0.6.2 → 0.7.1

package/dist/subagents/sessions/capability.js

@@ -0,0 +1,214 @@
+import { CapabilityError, } from "../../capability-registry.js";
+import { isSubagentProvider } from "../profiles.js";
+import { subagentProviderContinuationSupported } from "../providers/continuation.js";
+import { SubagentDeliveryMailbox } from "./delivery-mailbox.js";
+import { executeSubagentRun, } from "./execution.js";
+import { SubagentSessionError, SubagentSessionManager, } from "./manager.js";
+export class SubagentSessionCapability {
+    config;
+    activityLifecycle;
+    mailbox;
+    providerRunner;
+    constructor(config, activityLifecycle, options = {}) {
+        this.config = config;
+        this.activityLifecycle = activityLifecycle;
+        this.mailbox = new SubagentDeliveryMailbox(config.stateDir);
+        this.providerRunner = options.providerRunner ?? defaultProviderRunner;
+    }
+    async run(input, context, options) {
+        const manager = new SubagentSessionManager(this.config, {
+            launch: (request) => this.launch(request),
+        });
+        try {
+            switch (input.operation) {
+                case "start": {
+                    const started = await manager.start({
+                        workspaceId: context.workspaceId,
+                        workspaceRoot: context.workspaceRoot,
+                        target: input.target,
+                        prompt: input.prompt,
+                        model: input.model,
+                        thinking: input.thinking,
+                        activityId: options.activityId,
+                    });
+                    return {
+                        value: {
+                            operation: "start",
+                            session: publicSession(started.session),
+                            run: publicRun(started.run),
+                        },
+                    };
+                }
+                case "resume": {
+                    const resumed = manager.resume({
+                        sessionId: input.sessionId,
+                        prompt: input.prompt,
+                        activityId: options.activityId,
+                    }, { workspaceId: context.workspaceId });
+                    return {
+                        value: {
+                            operation: "resume",
+                            session: publicSession(resumed.session),
+                            run: publicRun(resumed.run),
+                        },
+                    };
+                }
+                case "status": {
+                    const session = manager.get(input.sessionId, { workspaceId: context.workspaceId });
+                    if (!session) {
+                        throw new SubagentSessionError("subagent.session_not_found", `Unknown Subagent Session in this Workspace: ${input.sessionId}`);
+                    }
+                    return {
+                        value: {
+                            operation: "status",
+                            session: publicSession(session),
+                            ...(session.activeRun ? { activeRun: publicRun(session.activeRun) } : {}),
+                            ...(session.latestRun ? { latestRun: publicRun(session.latestRun) } : {}),
+                        },
+                    };
+                }
+                case "list":
+                    return {
+                        value: {
+                            operation: "list",
+                            sessions: manager.list({ workspaceId: context.workspaceId }).map(publicSessionSummary),
+                        },
+                    };
+            }
+        }
+        catch (error) {
+            if (error instanceof SubagentSessionError) {
+                throw new CapabilityError(error.code, error.message);
+            }
+            throw error;
+        }
+        finally {
+            manager.close();
+        }
+    }
+    decorateResult(workspaceId, result) {
+        if (typeof result !== "object" || result === null)
+            return result;
+        const content = result.content;
+        if (!Array.isArray(content))
+            return result;
+        const excludeRunId = currentRunId(result);
+        const deliveries = this.mailbox.claimWorkspace(workspaceId, excludeRunId);
+        if (deliveries.length === 0)
+            return result;
+        return {
+            ...result,
+            content: [
+                ...content,
+                ...deliveries.map((delivery) => ({ type: "text", text: deliveryText(delivery) })),
+            ],
+        };
+    }
+    launch(request) {
+        void executeSubagentRun(this.config, request, this.providerRunner)
+            .then((completion) => this.recordCompletion(completion))
+            .catch(() => {
+            // The worker writes durable Session/mailbox state for provider failures.
+            // An unexpected orchestration failure must not become an unhandled rejection.
+        });
+    }
+    recordCompletion(completion) {
+        if (!completion.activityId)
+            return;
+        this.activityLifecycle.recordLinked({
+            sourceActivityId: completion.activityId,
+            tool: "subagent_result",
+            request: {
+                sessionId: completion.sessionId,
+                runId: completion.runId,
+            },
+            result: {
+                sessionId: completion.sessionId,
+                runId: completion.runId,
+                provider: completion.provider,
+                status: completion.outcome,
+            },
+            outcome: completion.outcome === "failed"
+                ? { type: "failed", error: "Subagent Run failed." }
+                : { type: "succeeded" },
+        });
+    }
+}
+function publicSession(session) {
+    const continuationSupported = sessionContinuationSupported(session);
+    return {
+        id: session.id,
+        status: session.status,
+        profileName: session.profileName,
+        provider: session.provider,
+        continuationSupported,
+        resumable: continuationSupported && session.status === "idle" && Boolean(session.providerSessionId),
+        ...(session.model ? { model: session.model } : {}),
+        ...(session.thinking ? { thinking: session.thinking } : {}),
+        ...(session.activeRun ? { activeRun: publicRun(session.activeRun) } : {}),
+        ...(session.latestRun ? { latestRun: publicRun(session.latestRun) } : {}),
+        createdAt: session.createdAt,
+        updatedAt: session.updatedAt,
+    };
+}
+function publicSessionSummary(session) {
+    const continuationSupported = sessionContinuationSupported(session);
+    return {
+        id: session.id,
+        status: session.status,
+        profileName: session.profileName,
+        provider: session.provider,
+        continuationSupported,
+        resumable: continuationSupported && session.status === "idle" && Boolean(session.providerSessionId),
+        ...(session.model ? { model: session.model } : {}),
+        ...(session.thinking ? { thinking: session.thinking } : {}),
+        ...(session.activeRun ? { activeRunId: session.activeRun.id } : {}),
+        ...(session.latestRun ? {
+            latestRun: {
+                id: session.latestRun.id,
+                status: session.latestRun.status,
+            },
+        } : {}),
+        updatedAt: session.updatedAt,
+    };
+}
+function sessionContinuationSupported(session) {
+    return isSubagentProvider(session.provider)
+        ? subagentProviderContinuationSupported(session.provider)
+        : false;
+}
+function publicRun(run) {
+    return {
+        id: run.id,
+        status: run.status,
+        ...(run.startedAt ? { startedAt: run.startedAt } : {}),
+        ...(run.finishedAt ? { finishedAt: run.finishedAt } : {}),
+    };
+}
+function currentRunId(result) {
+    if (typeof result !== "object" || result === null)
+        return undefined;
+    const structured = result.structuredContent;
+    if (typeof structured !== "object" || structured === null)
+        return undefined;
+    const capabilityResult = structured.result;
+    if (typeof capabilityResult !== "object" || capabilityResult === null)
+        return undefined;
+    const run = capabilityResult.run;
+    if (typeof run !== "object" || run === null)
+        return undefined;
+    const id = run.id;
+    return typeof id === "string" ? id : undefined;
+}
+function deliveryText(delivery) {
+    const header = `Subagent ${delivery.sessionId} Run ${delivery.runId} ${delivery.outcome}.`;
+    const body = delivery.outcome === "succeeded"
+        ? delivery.finalResponse
+        : delivery.error;
+    const suffix = delivery.truncated ? "\n[Subagent result truncated for delivery.]" : "";
+    return body ? `${header}\n${body}${suffix}` : `${header}${suffix}`;
+}
+async function defaultProviderRunner(provider, input) {
+    const { runSubagentProvider } = await import("../providers/registry.js");
+    return runSubagentProvider(provider, input);
+}

package/dist/subagents/sessions/delivery-mailbox.js

@@ -0,0 +1,115 @@
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+const MAX_DELIVERY_TEXT_BYTES = 64 * 1024;
+const MAX_DELIVERIES_PER_RESPONSE = 4;
+export class SubagentDeliveryMailbox {
+    directory;
+    constructor(stateDir) {
+        this.directory = join(stateDir, "subagent-delivery");
+    }
+    write(input) {
+        const response = boundText(input.finalResponse);
+        const error = boundText(input.error);
+        const delivery = {
+            sessionId: input.sessionId,
+            runId: input.runId,
+            workspaceId: input.workspaceId,
+            ...(input.activityId ? { activityId: input.activityId } : {}),
+            provider: input.provider,
+            outcome: input.outcome,
+            ...(response.text !== undefined ? { finalResponse: response.text } : {}),
+            ...(error.text !== undefined ? { error: error.text } : {}),
+            truncated: response.truncated || error.truncated,
+            createdAt: new Date().toISOString(),
+        };
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        const path = this.pathFor(delivery.sessionId);
+        const temporary = `${path}.${process.pid}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify(delivery)}\n`, { mode: 0o600 });
+        rmSync(path, { force: true });
+        renameSync(temporary, path);
+        return delivery;
+    }
+    claimWorkspace(workspaceId, excludeRunId) {
+        return this.claim((delivery) => delivery.workspaceId === workspaceId && delivery.runId !== excludeRunId);
+    }
+    claimSession(workspaceId, sessionId) {
+        return this.claim((delivery) => delivery.workspaceId === workspaceId && delivery.sessionId === sessionId);
+    }
+    hasSession(sessionId) {
+        return this.files().includes(`${sessionId}.json`);
+    }
+    claim(predicate) {
+        const deliveries = [];
+        for (const file of this.files()) {
+            if (deliveries.length >= MAX_DELIVERIES_PER_RESPONSE)
+                break;
+            const path = join(this.directory, file);
+            const delivery = readDelivery(path);
+            if (!delivery || !predicate(delivery))
+                continue;
+            rmSync(path, { force: true });
+            deliveries.push(delivery);
+        }
+        return deliveries.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+    }
+    files() {
+        try {
+            return readdirSync(this.directory)
+                .filter((file) => /^agt_[a-z0-9]+\.json$/i.test(file))
+                .sort();
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+    }
+    pathFor(sessionId) {
+        if (!/^agt_[a-z0-9]+$/i.test(sessionId))
+            throw new Error(`Invalid Subagent Session id: ${sessionId}`);
+        return join(this.directory, `${sessionId}.json`);
+    }
+}
+function readDelivery(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof value.sessionId !== "string" ||
+            typeof value.runId !== "string" ||
+            typeof value.workspaceId !== "string" ||
+            typeof value.provider !== "string" ||
+            !isOutcome(value.outcome) ||
+            typeof value.createdAt !== "string") {
+            return undefined;
+        }
+        return {
+            sessionId: value.sessionId,
+            runId: value.runId,
+            workspaceId: value.workspaceId,
+            ...(typeof value.activityId === "string" ? { activityId: value.activityId } : {}),
+            provider: value.provider,
+            outcome: value.outcome,
+            ...(typeof value.finalResponse === "string" ? { finalResponse: value.finalResponse } : {}),
+            ...(typeof value.error === "string" ? { error: value.error } : {}),
+            truncated: value.truncated === true,
+            createdAt: value.createdAt,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function boundText(value) {
+    if (value === undefined)
+        return { truncated: false };
+    const bytes = Buffer.from(value, "utf8");
+    if (bytes.length <= MAX_DELIVERY_TEXT_BYTES)
+        return { text: value, truncated: false };
+    return {
+        text: bytes.subarray(0, MAX_DELIVERY_TEXT_BYTES).toString("utf8"),
+        truncated: true,
+    };
+}
+function isOutcome(value) {
+    return value === "succeeded" || value === "failed" || value === "cancelled" || value === "interrupted";
+}

package/dist/subagents/sessions/execution.js

@@ -0,0 +1,171 @@
+import { HookRunner } from "../../hooks.js";
+import { isSubagentProvider, loadSubagentProfiles, } from "../profiles.js";
+import { runSubagentProvider } from "../providers/registry.js";
+import { SubagentDeliveryMailbox } from "./delivery-mailbox.js";
+import { createSubagentSessionStore, } from "./store.js";
+export async function executeSubagentRun(config, input, providerRunner = runSubagentProvider) {
+    const store = createSubagentSessionStore(config);
+    const mailbox = new SubagentDeliveryMailbox(config.stateDir);
+    try {
+        const record = store.get(input.sessionId);
+        if (!record)
+            throw new Error(`Unknown subagent id: ${input.sessionId}`);
+        if (record.activeRun?.id !== input.runId) {
+            throw new Error(`Subagent Run ${input.runId} is not active for Session ${record.id}.`);
+        }
+        const hooks = new HookRunner(config.hooks, config.logging);
+        const hookInvocation = {
+            workspaceId: record.workspaceId,
+            workspaceRoot: record.workspaceRoot,
+            payload: {
+                agentId: record.id,
+                sessionId: record.id,
+                runId: input.runId,
+                profile: record.profileName,
+                provider: record.provider,
+                model: record.model,
+                thinking: record.thinking,
+            },
+        };
+        await hooks.run("SubagentStart", hookInvocation);
+        try {
+            const result = await runSessionProvider(config, record, input.prompt, providerRunner);
+            await hooks.run("SubagentStop", {
+                ...hookInvocation,
+                payload: {
+                    ...hookInvocation.payload,
+                    status: "succeeded",
+                    providerSessionId: result.providerSessionId,
+                },
+            });
+            const finishedAt = new Date().toISOString();
+            store.update(record.id, {
+                providerSessionId: result.providerSessionId ?? undefined,
+                status: "idle",
+                activeRun: undefined,
+                latestRun: {
+                    id: input.runId,
+                    status: "succeeded",
+                    finishedAt,
+                },
+            });
+            if (record.workspaceId) {
+                mailbox.write({
+                    sessionId: record.id,
+                    runId: input.runId,
+                    workspaceId: record.workspaceId,
+                    ...(input.activityId ? { activityId: input.activityId } : {}),
+                    provider: record.provider,
+                    outcome: "succeeded",
+                    finalResponse: result.finalResponse,
+                });
+            }
+            return completion(record, input, "succeeded");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            await hooks.run("SubagentStop", {
+                ...hookInvocation,
+                payload: {
+                    ...hookInvocation.payload,
+                    status: "failed",
+                },
+            });
+            const finishedAt = new Date().toISOString();
+            store.update(record.id, {
+                status: "idle",
+                activeRun: undefined,
+                latestRun: {
+                    id: input.runId,
+                    status: "failed",
+                    finishedAt,
+                },
+            });
+            if (record.workspaceId) {
+                mailbox.write({
+                    sessionId: record.id,
+                    runId: input.runId,
+                    workspaceId: record.workspaceId,
+                    ...(input.activityId ? { activityId: input.activityId } : {}),
+                    provider: record.provider,
+                    outcome: "failed",
+                    error: message,
+                });
+            }
+            return completion(record, input, "failed", message);
+        }
+    }
+    finally {
+        store.close();
+    }
+}
+export async function executeSubagentSession(config, sessionId, prompt) {
+    const store = createSubagentSessionStore(config);
+    try {
+        const record = store.get(sessionId);
+        if (!record)
+            throw new Error(`Unknown subagent id: ${sessionId}`);
+        if (!record.activeRun)
+            throw new Error(`Subagent Session ${sessionId} has no active Run.`);
+        return executeSubagentRun(config, {
+            sessionId,
+            runId: record.activeRun.id,
+            ...(record.activeRun.activityId ? { activityId: record.activeRun.activityId } : {}),
+            prompt,
+        });
+    }
+    finally {
+        store.close();
+    }
+}
+async function runSessionProvider(config, session, prompt, providerRunner) {
+    if (!isSubagentProvider(session.provider)) {
+        throw new Error(`Unknown subagent provider for Session ${session.id}: ${session.provider}`);
+    }
+    if (session.providerSessionId) {
+        return providerRunner(session.provider, {
+            prompt,
+            workspace: session.workspaceRoot,
+            providerSessionId: session.providerSessionId,
+            writeMode: "allowed",
+            model: session.model,
+            thinking: session.thinking,
+        });
+    }
+    if (session.profileName === session.provider) {
+        return providerRunner(session.provider, {
+            prompt,
+            workspace: session.workspaceRoot,
+            writeMode: "allowed",
+            model: session.model,
+            thinking: session.thinking,
+        });
+    }
+    const profiles = await loadSubagentProfiles(config, session.workspaceRoot);
+    const profile = profiles.find((candidate) => candidate.name === session.profileName);
+    if (!profile)
+        throw new Error(`Subagent profile not found: ${session.profileName}`);
+    return runSubagentProfile(profile, session, prompt, providerRunner);
+}
+async function runSubagentProfile(profile, session, prompt, providerRunner) {
+    const body = profile.body.trim();
+    const firstPrompt = body ? `${body}\n\nTask:\n${prompt}` : prompt;
+    return providerRunner(session.provider, {
+        prompt: firstPrompt,
+        workspace: session.workspaceRoot,
+        writeMode: "allowed",
+        model: session.model,
+        thinking: session.thinking,
+    });
+}
+function completion(session, input, outcome, error) {
+    return {
+        sessionId: session.id,
+        runId: input.runId,
+        workspaceId: session.workspaceId,
+        activityId: input.activityId,
+        provider: session.provider,
+        outcome,
+        ...(error ? { error } : {}),
+    };
+}

package/dist/subagents/sessions/manager.js

@@ -0,0 +1,107 @@
+import { randomUUID } from "node:crypto";
+import { formatAvailableSubagentTargets, resolveSubagentTarget, } from "../cli-target.js";
+import { isSubagentProvider, loadSubagentProfiles, } from "../profiles.js";
+import { assertSubagentProviderAvailable } from "../providers/availability.js";
+import { subagentProviderContinuationSupported } from "../providers/continuation.js";
+import { createSubagentSessionStore, } from "./store.js";
+export class SubagentSessionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SubagentSessionError";
+    }
+}
+export class SubagentSessionManager {
+    config;
+    launcher;
+    store;
+    constructor(config, launcher) {
+        this.config = config;
+        this.launcher = launcher;
+        this.store = createSubagentSessionStore(config);
+    }
+    list(scope = {}) {
+        return this.store.list(scope);
+    }
+    get(idOrPrefix, scope) {
+        return scope ? this.store.getInScope(idOrPrefix, scope) : this.store.get(idOrPrefix);
+    }
+    async start(input) {
+        const profiles = await loadSubagentProfiles(this.config, input.workspaceRoot);
+        const target = resolveSubagentTarget(input.target, profiles, input.model, input.thinking);
+        if (!target) {
+            throw new Error(`Unknown subagent profile or provider: ${input.target}. Available ${formatAvailableSubagentTargets(profiles)}`);
+        }
+        assertSubagentProviderAvailable(target.provider);
+        const runId = newRunId();
+        const startedAt = new Date().toISOString();
+        const session = this.store.create({
+            workspaceId: input.workspaceId,
+            workspaceRoot: input.workspaceRoot,
+            profileName: target.name,
+            provider: target.provider,
+            model: target.model,
+            thinking: target.thinking,
+            activeRun: {
+                id: runId,
+                ...(input.activityId ? { activityId: input.activityId } : {}),
+                startedAt,
+            },
+        });
+        const run = session.activeRun;
+        if (!run)
+            throw new Error(`Subagent Session ${session.id} did not create an active Run.`);
+        this.launcher.launch({
+            sessionId: session.id,
+            runId,
+            ...(input.activityId ? { activityId: input.activityId } : {}),
+            prompt: input.prompt,
+        });
+        return { session, run };
+    }
+    resume(input, scope = {}) {
+        const existing = this.store.getInScope(input.sessionId, scope);
+        if (!existing) {
+            throw new SubagentSessionError("subagent.session_not_found", `Unknown Subagent Session in this Workspace: ${input.sessionId}`);
+        }
+        if (existing.activeRun) {
+            throw new SubagentSessionError("subagent.busy", `Subagent Session ${existing.id} already has active Run ${existing.activeRun.id}.`);
+        }
+        if (!isSubagentProvider(existing.provider)) {
+            throw new Error(`Unknown subagent provider for existing session: ${existing.provider}`);
+        }
+        if (!subagentProviderContinuationSupported(existing.provider)) {
+            throw new SubagentSessionError("subagent.continuation_unsupported", `${existing.provider} does not support true Subagent Session continuation.`);
+        }
+        if (!existing.providerSessionId) {
+            throw new SubagentSessionError("subagent.continuation_unavailable", `Subagent Session ${existing.id} has no provider continuation identity.`);
+        }
+        assertSubagentProviderAvailable(existing.provider);
+        const runId = newRunId();
+        const startedAt = new Date().toISOString();
+        const run = {
+            id: runId,
+            status: "running",
+            ...(input.activityId ? { activityId: input.activityId } : {}),
+            startedAt,
+        };
+        const session = this.store.update(existing.id, {
+            status: "running",
+            activeRun: run,
+        });
+        this.launcher.launch({
+            sessionId: session.id,
+            runId,
+            ...(input.activityId ? { activityId: input.activityId } : {}),
+            prompt: input.prompt,
+        });
+        return { session, run };
+    }
+    close() {
+        this.store.close();
+    }
+}
+function newRunId() {
+    return `run_${randomUUID().replaceAll("-", "").slice(0, 12)}`;
+}

package/dist/subagents/sessions/mcp/audit.js

@@ -0,0 +1,85 @@
+export function capabilityActivityAuditRequest(input) {
+    if (input.name !== "subagent.session") {
+        return {
+            workspaceId: input.workspaceId,
+            name: input.name,
+            action: "run",
+            arguments: input.arguments,
+            file: input.file,
+        };
+    }
+    const argumentsValue = isAuditRecord(input.arguments) ? input.arguments : {};
+    return {
+        workspaceId: input.workspaceId,
+        name: input.name,
+        action: "run",
+        arguments: {
+            operation: argumentsValue.operation,
+            ...(typeof argumentsValue.target === "string" ? { target: argumentsValue.target } : {}),
+            ...(typeof argumentsValue.sessionId === "string" ? { sessionId: argumentsValue.sessionId } : {}),
+            ...(typeof argumentsValue.model === "string" ? { model: argumentsValue.model } : {}),
+            ...(typeof argumentsValue.thinking === "string" ? { thinking: argumentsValue.thinking } : {}),
+            ...(typeof argumentsValue.prompt === "string" ? { promptLength: argumentsValue.prompt.length } : {}),
+        },
+    };
+}
+export function capabilityActivityAuditResult(name, result) {
+    if (name !== "subagent.session" || !isAuditRecord(result))
+        return result;
+    const structuredContent = isAuditRecord(result.structuredContent) ? result.structuredContent : undefined;
+    const capabilityResult = structuredContent && isAuditRecord(structuredContent.result)
+        ? structuredContent.result
+        : undefined;
+    const error = structuredContent && isAuditRecord(structuredContent.error)
+        ? structuredContent.error
+        : undefined;
+    return {
+        name,
+        action: "run",
+        ...(capabilityResult ? { result: summarizeSubagentCapabilityResult(capabilityResult) } : {}),
+        ...(error
+            ? {
+                error: {
+                    code: error.code,
+                    message: error.message,
+                },
+            }
+            : {}),
+    };
+}
+function isAuditRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function summarizeSubagentCapabilityResult(result) {
+    const summary = { operation: result.operation };
+    const session = isAuditRecord(result.session) ? result.session : undefined;
+    if (session) {
+        summary.session = {
+            id: session.id,
+            status: session.status,
+            profileName: session.profileName,
+            provider: session.provider,
+            model: session.model,
+            thinking: session.thinking,
+        };
+    }
+    for (const key of ["run", "activeRun", "latestRun"]) {
+        const run = isAuditRecord(result[key]) ? result[key] : undefined;
+        if (run)
+            summary[key] = { id: run.id, status: run.status };
+    }
+    if (Array.isArray(result.sessions)) {
+        summary.sessions = result.sessions.flatMap((entry) => {
+            if (!isAuditRecord(entry))
+                return [];
+            return [{
+                    id: entry.id,
+                    status: entry.status,
+                    profileName: entry.profileName,
+                    provider: entry.provider,
+                    activeRunId: entry.activeRunId,
+                }];
+        });
+    }
+    return summary;
+}