@grackle-ai/server 0.54.1 → 0.56.0

package/dist/stream-registry.d.ts

@@ -0,0 +1,76 @@
+/**
+ * In-memory stream registry for agent-to-agent IPC.
+ *
+ * Streams are global named message channels. Sessions interact with streams
+ * through subscriptions (fds) that have permissions (rw/r/w) and delivery
+ * modes (sync/async/detach). This is separate from stream-hub.ts, which
+ * handles UI event broadcasting.
+ *
+ * Streams are ephemeral — they don't survive server restart. The session
+ * JSONL is the durable state; streams are recreated on reanimate.
+ */
+/** Permission level for a subscription. */
+export type Permission = "rw" | "r" | "w";
+/** How a subscriber receives messages. */
+export type DeliveryMode = "sync" | "async" | "detach";
+/** A global named message channel. */
+export interface Stream {
+    readonly id: string;
+    readonly name: string;
+    readonly messages: StreamMessage[];
+    readonly subscriptions: Map<string, Subscription>;
+}
+/** A message published to a stream. */
+export interface StreamMessage {
+    readonly id: string;
+    readonly senderId: string;
+    readonly content: string;
+    readonly timestamp: string;
+    /** Subscription IDs that have consumed this message. */
+    readonly deliveredTo: Set<string>;
+}
+/** A session's reference to a stream (an "fd"). */
+export interface Subscription {
+    readonly id: string;
+    readonly fd: number;
+    readonly streamId: string;
+    readonly sessionId: string;
+    readonly permission: Permission;
+    readonly deliveryMode: DeliveryMode;
+    /** True if the session opened this fd via spawn(); false if inherited from parent. */
+    readonly createdBySpawn: boolean;
+}
+/** Callback invoked when a message arrives on an async subscription. */
+export type AsyncMessageListener = (sub: Subscription, msg: StreamMessage) => void;
+/** Create a new named stream. Names must be unique — throws if a stream with the same name exists. */
+export declare function createStream(name: string): Stream;
+/** Retrieve a stream by ID. */
+export declare function getStream(id: string): Stream | undefined;
+/** Retrieve a stream by name. */
+export declare function getStreamByName(name: string): Stream | undefined;
+/** Remove a stream and all its subscriptions. */
+export declare function deleteStream(id: string): void;
+/** Create a subscription (fd) for a session on a stream. */
+export declare function subscribe(streamId: string, sessionId: string, permission: Permission, deliveryMode: DeliveryMode, createdBySpawn: boolean): Subscription;
+/** Remove a subscription. Deletes the stream if it was the last subscription. */
+export declare function unsubscribe(subscriptionId: string): void;
+/** Look up a subscription by session ID and fd number. */
+export declare function getSubscription(sessionId: string, fd: number): Subscription | undefined;
+/** Get all subscriptions for a session. */
+export declare function getSubscriptionsForSession(sessionId: string): Subscription[];
+/** Get only subscriptions that this session opened via spawn() (not inherited). */
+export declare function getOwnedSubscriptions(sessionId: string): Subscription[];
+/** Publish a message to a stream. Notifies async subscribers and enqueues for sync subscribers. */
+export declare function publish(streamId: string, senderId: string, content: string): StreamMessage;
+/** Block until an undelivered message is available for this sync subscription. */
+export declare function consumeSync(subscriptionId: string): Promise<StreamMessage>;
+/** Check if there are messages in the stream buffer not yet delivered to this subscription. */
+export declare function hasUndeliveredMessages(subscriptionId: string): boolean;
+/**
+ * Register a callback invoked when a message arrives on any async subscription
+ * for the given session. Returns an unsubscribe function.
+ */
+export declare function registerAsyncListener(sessionId: string, callback: AsyncMessageListener): () => void;
+/** Clear all state. For testing only. */
+export declare function _resetForTesting(): void;
+//# sourceMappingURL=stream-registry.d.ts.map

package/dist/stream-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-registry.d.ts","sourceRoot":"","sources":["../src/stream-registry.ts"],"names":[],"mappings":"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"}

package/dist/stream-registry.js

@@ -0,0 +1,342 @@
+/**
+ * In-memory stream registry for agent-to-agent IPC.
+ *
+ * Streams are global named message channels. Sessions interact with streams
+ * through subscriptions (fds) that have permissions (rw/r/w) and delivery
+ * modes (sync/async/detach). This is separate from stream-hub.ts, which
+ * handles UI event broadcasting.
+ *
+ * Streams are ephemeral — they don't survive server restart. The session
+ * JSONL is the durable state; streams are recreated on reanimate.
+ */
+import { v4 as uuid } from "uuid";
+import { logger } from "./logger.js";
+// ─── Async Queue (blocking reads for sync subscriptions) ──────────────────────
+/** Simple async queue for blocking consume. Rejects pending waiters on close. */
+class AsyncQueue {
+    queue = [];
+    waiters = [];
+    closed = false;
+    push(item) {
+        if (this.closed) {
+            return;
+        }
+        if (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            waiter.resolve(item);
+        }
+        else {
+            this.queue.push(item);
+        }
+    }
+    async shift() {
+        if (this.queue.length > 0) {
+            return this.queue.shift();
+        }
+        if (this.closed) {
+            throw new Error("Queue is closed");
+        }
+        return new Promise((resolve, reject) => {
+            this.waiters.push({ resolve, reject });
+        });
+    }
+    /** Close the queue. Rejects all pending waiters so blocked consumers unblock. */
+    close() {
+        this.closed = true;
+        const err = new Error("Subscription closed");
+        for (const waiter of this.waiters) {
+            waiter.reject(err);
+        }
+        this.waiters.length = 0;
+    }
+}
+// ─── Module State ─────────────────────────────────────────────────────────────
+/** All active streams, keyed by stream ID. */
+const streams = new Map();
+/** Name → stream ID index for unique-name lookup. */
+const streamsByName = new Map();
+/** All subscriptions for each session, keyed by sessionId → fd → Subscription. */
+const subscriptionsBySession = new Map();
+/** Subscription ID → Subscription (for fast lookup by ID). */
+const subscriptionsById = new Map();
+/** Next fd number for each session (starts at 3, increments). */
+const fdCounters = new Map();
+/** Async message listeners keyed by session ID. Invoked when a message arrives on an async subscription. */
+const asyncListeners = new Map();
+/** Blocking queues for sync subscriptions, keyed by subscription ID. */
+const syncQueues = new Map();
+// ─── Internal Helpers ─────────────────────────────────────────────────────────
+/** Allocate the next fd number for a session. */
+function nextFd(sessionId) {
+    const current = fdCounters.get(sessionId) ?? 3;
+    fdCounters.set(sessionId, current + 1);
+    return current;
+}
+/** Get or create the fd map for a session. */
+function getSessionFdMap(sessionId) {
+    let fdMap = subscriptionsBySession.get(sessionId);
+    if (!fdMap) {
+        fdMap = new Map();
+        subscriptionsBySession.set(sessionId, fdMap);
+    }
+    return fdMap;
+}
+/** Clean up session state when it has no more subscriptions. */
+function cleanupSessionIfEmpty(sessionId) {
+    const fdMap = subscriptionsBySession.get(sessionId);
+    if (fdMap?.size === 0) {
+        subscriptionsBySession.delete(sessionId);
+        fdCounters.delete(sessionId);
+    }
+}
+/** Check if a subscription can receive messages (has read permission). */
+function canReceive(sub) {
+    return sub.permission === "rw" || sub.permission === "r";
+}
+/**
+ * Prune messages that have been delivered to all readable subscriptions.
+ * Keeps memory bounded by removing messages no longer needed for hasUndeliveredMessages.
+ */
+function pruneDeliveredMessages(stream) {
+    const readableSubs = Array.from(stream.subscriptions.values()).filter(canReceive);
+    if (readableSubs.length === 0) {
+        stream.messages.length = 0;
+        return;
+    }
+    let pruneCount = 0;
+    for (const msg of stream.messages) {
+        const allDelivered = readableSubs.every((sub) => msg.deliveredTo.has(sub.id) || msg.senderId === sub.sessionId);
+        if (allDelivered) {
+            pruneCount++;
+        }
+        else {
+            break; // Messages are ordered; stop at first undelivered
+        }
+    }
+    if (pruneCount > 0) {
+        stream.messages.splice(0, pruneCount);
+    }
+}
+// ─── Stream Lifecycle ─────────────────────────────────────────────────────────
+/** Create a new named stream. Names must be unique — throws if a stream with the same name exists. */
+export function createStream(name) {
+    if (streamsByName.has(name)) {
+        throw new Error(`Stream with name "${name}" already exists`);
+    }
+    const stream = {
+        id: uuid(),
+        name,
+        messages: [],
+        subscriptions: new Map(),
+    };
+    streams.set(stream.id, stream);
+    streamsByName.set(name, stream.id);
+    return stream;
+}
+/** Retrieve a stream by ID. */
+export function getStream(id) {
+    return streams.get(id);
+}
+/** Retrieve a stream by name. */
+export function getStreamByName(name) {
+    const id = streamsByName.get(name);
+    return id ? streams.get(id) : undefined;
+}
+/** Remove a stream and all its subscriptions. */
+export function deleteStream(id) {
+    const stream = streams.get(id);
+    if (!stream) {
+        return;
+    }
+    // Clean up all subscriptions on this stream
+    for (const sub of stream.subscriptions.values()) {
+        subscriptionsById.delete(sub.id);
+        const queue = syncQueues.get(sub.id);
+        if (queue) {
+            queue.close();
+            syncQueues.delete(sub.id);
+        }
+        const fdMap = subscriptionsBySession.get(sub.sessionId);
+        if (fdMap) {
+            fdMap.delete(sub.fd);
+            cleanupSessionIfEmpty(sub.sessionId);
+        }
+    }
+    streamsByName.delete(stream.name);
+    streams.delete(id);
+}
+// ─── Subscriptions ────────────────────────────────────────────────────────────
+/** Create a subscription (fd) for a session on a stream. */
+export function subscribe(streamId, sessionId, permission, deliveryMode, createdBySpawn) {
+    const stream = streams.get(streamId);
+    if (!stream) {
+        throw new Error(`Stream not found: ${streamId}`);
+    }
+    // w-only subscriptions cannot have sync or async delivery (they never receive)
+    if (permission === "w" && (deliveryMode === "sync" || deliveryMode === "async")) {
+        throw new Error(`Write-only subscription cannot use "${deliveryMode}" delivery mode`);
+    }
+    const fd = nextFd(sessionId);
+    const sub = {
+        id: uuid(),
+        fd,
+        streamId,
+        sessionId,
+        permission,
+        deliveryMode,
+        createdBySpawn,
+    };
+    stream.subscriptions.set(sub.id, sub);
+    getSessionFdMap(sessionId).set(fd, sub);
+    subscriptionsById.set(sub.id, sub);
+    // Create a blocking queue for sync subscriptions (only readable ones)
+    if (deliveryMode === "sync" && canReceive(sub)) {
+        syncQueues.set(sub.id, new AsyncQueue());
+    }
+    return sub;
+}
+/** Remove a subscription. Deletes the stream if it was the last subscription. */
+export function unsubscribe(subscriptionId) {
+    const sub = subscriptionsById.get(subscriptionId);
+    if (!sub) {
+        return;
+    }
+    // Close and remove sync queue (unblocks any pending consumeSync)
+    const queue = syncQueues.get(sub.id);
+    if (queue) {
+        queue.close();
+        syncQueues.delete(sub.id);
+    }
+    // Remove from stream
+    const stream = streams.get(sub.streamId);
+    if (stream) {
+        stream.subscriptions.delete(sub.id);
+        if (stream.subscriptions.size === 0) {
+            streamsByName.delete(stream.name);
+            streams.delete(sub.streamId);
+        }
+    }
+    // Remove from session fd map
+    const fdMap = subscriptionsBySession.get(sub.sessionId);
+    if (fdMap) {
+        fdMap.delete(sub.fd);
+        cleanupSessionIfEmpty(sub.sessionId);
+    }
+    // Remove from lookup maps
+    subscriptionsById.delete(sub.id);
+}
+/** Look up a subscription by session ID and fd number. */
+export function getSubscription(sessionId, fd) {
+    return subscriptionsBySession.get(sessionId)?.get(fd);
+}
+/** Get all subscriptions for a session. */
+export function getSubscriptionsForSession(sessionId) {
+    const fdMap = subscriptionsBySession.get(sessionId);
+    if (!fdMap) {
+        return [];
+    }
+    return Array.from(fdMap.values());
+}
+/** Get only subscriptions that this session opened via spawn() (not inherited). */
+export function getOwnedSubscriptions(sessionId) {
+    return getSubscriptionsForSession(sessionId).filter((s) => s.createdBySpawn);
+}
+// ─── Messaging ────────────────────────────────────────────────────────────────
+/** Publish a message to a stream. Notifies async subscribers and enqueues for sync subscribers. */
+export function publish(streamId, senderId, content) {
+    const stream = streams.get(streamId);
+    if (!stream) {
+        throw new Error(`Stream not found: ${streamId}`);
+    }
+    const msg = {
+        id: uuid(),
+        senderId,
+        content,
+        timestamp: new Date().toISOString(),
+        deliveredTo: new Set(),
+    };
+    stream.messages.push(msg);
+    // Notify subscribers (skip the sender and write-only subscriptions)
+    for (const sub of stream.subscriptions.values()) {
+        if (sub.sessionId === senderId) {
+            continue;
+        }
+        if (!canReceive(sub)) {
+            continue;
+        }
+        if (sub.deliveryMode === "async") {
+            // Only mark as delivered if the listener exists and succeeds
+            const listener = asyncListeners.get(sub.sessionId);
+            if (listener) {
+                try {
+                    listener(sub, msg);
+                    msg.deliveredTo.add(sub.id);
+                }
+                catch (err) {
+                    logger.warn({ err, subscriptionId: sub.id }, "Async listener threw — message left undelivered");
+                }
+            }
+            // No listener registered: message stays undelivered (buffered)
+        }
+        else if (sub.deliveryMode === "sync") {
+            // Enqueue for blocking consumeSync()
+            const queue = syncQueues.get(sub.id);
+            if (queue) {
+                queue.push(msg);
+            }
+        }
+        // "detach" mode: message stays in buffer, no notification
+    }
+    // Prune messages that have been fully delivered
+    pruneDeliveredMessages(stream);
+    return msg;
+}
+/** Block until an undelivered message is available for this sync subscription. */
+export async function consumeSync(subscriptionId) {
+    const queue = syncQueues.get(subscriptionId);
+    if (!queue) {
+        throw new Error(`No sync queue for subscription: ${subscriptionId}. Is it a sync subscription?`);
+    }
+    const msg = await queue.shift();
+    msg.deliveredTo.add(subscriptionId);
+    return msg;
+}
+/** Check if there are messages in the stream buffer not yet delivered to this subscription. */
+export function hasUndeliveredMessages(subscriptionId) {
+    const sub = subscriptionsById.get(subscriptionId);
+    if (!sub) {
+        return false;
+    }
+    const stream = streams.get(sub.streamId);
+    if (!stream) {
+        return false;
+    }
+    return stream.messages.some((msg) => !msg.deliveredTo.has(subscriptionId) && msg.senderId !== sub.sessionId);
+}
+// ─── Notification Registration ────────────────────────────────────────────────
+/**
+ * Register a callback invoked when a message arrives on any async subscription
+ * for the given session. Returns an unsubscribe function.
+ */
+export function registerAsyncListener(sessionId, callback) {
+    asyncListeners.set(sessionId, callback);
+    return () => {
+        asyncListeners.delete(sessionId);
+    };
+}
+// ─── Testing ──────────────────────────────────────────────────────────────────
+/** Clear all state. For testing only. */
+export function _resetForTesting() {
+    streams.clear();
+    streamsByName.clear();
+    subscriptionsBySession.clear();
+    subscriptionsById.clear();
+    fdCounters.clear();
+    asyncListeners.clear();
+    // Close all sync queues before clearing
+    for (const queue of syncQueues.values()) {
+        queue.close();
+    }
+    syncQueues.clear();
+}
+//# sourceMappingURL=stream-registry.js.map

package/dist/stream-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-registry.js","sourceRoot":"","sources":["../src/stream-registry.ts"],"names":[],"mappings":"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"}

package/dist/system-prompt-builder.d.ts

@@ -1,7 +1,54 @@
 /**
  * Builds system prompts for agent sessions, assembling sections
  * dynamically based on the session type (task vs ad-hoc).
+ *
+ * Orchestrator tasks (canDecompose + depth <= 1) receive rich project
+ * context (task tree, persona roster, environments, findings).
+ * Leaf tasks receive the existing completion-contract template.
  */
+/** Lightweight task node for rendering the task tree in orchestrator prompts. */
+export interface TaskTreeNode {
+    /** Task ID. */
+    id: string;
+    /** Task title. */
+    title: string;
+    /** Current lifecycle status (not_started, working, paused, complete, failed). */
+    status: string;
+    /** Nesting depth in the hierarchy (0 = root). */
+    depth: number;
+    /** Parent task ID (empty string for root-level tasks). */
+    parentTaskId: string;
+    /** IDs of tasks this task depends on. */
+    dependsOn: string[];
+    /** Resolved persona display name (empty if none assigned). */
+    personaName: string;
+    /** Git branch name (empty if none). */
+    branch: string;
+    /** Whether this task can create subtasks. */
+    canDecompose: boolean;
+}
+/** Persona summary for the available-personas prompt section. */
+export interface PersonaSummary {
+    /** Display name. */
+    name: string;
+    /** Short description. */
+    description: string;
+    /** Runtime backend (claude-code, copilot, codex, etc.). */
+    runtime: string;
+    /** Default model (e.g. "opus", "sonnet"). */
+    model: string;
+}
+/** Environment summary for the available-environments prompt section. */
+export interface EnvironmentSummary {
+    /** Human-readable name. */
+    displayName: string;
+    /** Adapter backend (local, ssh, codespace, docker). */
+    adapterType: string;
+    /** Connection status (connected, disconnected, etc.). */
+    status: string;
+    /** Default runtime for this environment. */
+    defaultRuntime: string;
+}
 /** Options for building a system prompt. */
 export interface SystemPromptOptions {
     /** Task metadata. When absent, this is an ad-hoc session. */
@@ -10,15 +57,36 @@ export interface SystemPromptOptions {
         description: string;
         notes: string;
     };
+    /** ID of the current task (used to mark it in the task tree). */
+    taskId?: string;
     /** Whether the agent is allowed to create subtasks. */
     canDecompose?: boolean;
     /** Persona behavioral instructions (prepended when non-empty). */
     personaPrompt?: string;
+    /** Task depth in the hierarchy (0 = root, 1 = first child, etc.). */
+    taskDepth?: number;
+    /** Workspace metadata for the orchestrator context section. */
+    workspace?: {
+        name: string;
+        description: string;
+        repoUrl: string;
+    };
+    /** All tasks in the workspace, for rendering the task tree. */
+    taskTree?: TaskTreeNode[];
+    /** Available personas for the orchestrator to assign. */
+    availablePersonas?: PersonaSummary[];
+    /** Available environments for the orchestrator to route work to. */
+    availableEnvironments?: EnvironmentSummary[];
+    /** Pre-built findings context string (from buildFindingsContext). */
+    findingsContext?: string;
+    /** Invocation mode: fresh (first time) or resume (re-invoked after child completion). */
+    triggerMode?: "fresh" | "resume";
 }
 /**
  * Assembles a system prompt from discrete sections based on session type.
  *
- * Task sessions get task context, completion contract, signal docs, and findings guidance.
+ * Orchestrator tasks get project state, task tree, persona roster, and
+ * decomposition guidelines. Leaf tasks get the existing completion contract.
  * Ad-hoc sessions get only the MCP note and persona prompt.
  */
 export declare class SystemPromptBuilder {
@@ -26,6 +94,33 @@ export declare class SystemPromptBuilder {
     constructor(options: SystemPromptOptions);
     /** Build the complete system prompt string. */
     build(): string;
+    /**
+     * Determine whether this is an orchestrator task.
+     * Requires canDecompose, shallow depth, AND orchestrator data fields to be
+     * present. This ensures existing callers that pass canDecompose without
+     * the new fields still get the leaf template.
+     */
+    private isOrchestrator;
+    /** Orchestrator task context with role framing. */
+    private buildOrchestratorTaskContext;
+    /** Workspace metadata section. */
+    private buildWorkspaceContext;
+    /** Hierarchical task tree with statuses, personas, and dependencies. */
+    private buildTaskTree;
+    /** Available personas table. */
+    private buildAvailablePersonas;
+    /** Available environments table. */
+    private buildAvailableEnvironments;
+    /** Orchestrator findings section with actual findings data. */
+    private buildOrchestratorFindingsSection;
+    /** Trigger context describing why this invocation happened. */
+    private buildTriggerContext;
+    /** Decomposition heuristics and guardrails. */
+    private buildDecompositionGuidelines;
+    /** Orchestrator-specific MCP tool documentation. */
+    private buildOrchestratorTools;
+    /** Orchestrator-specific completion contract. */
+    private buildOrchestratorCompletionContract;
     /** Task title, description, and notes. */
     private buildTaskContext;
     /** Contract for signaling task completion. */
@@ -34,7 +129,7 @@ export declare class SystemPromptBuilder {
     private buildSubtaskSection;
     /** SIGCHLD signal documentation. */
     private buildSignalSection;
-    /** Guidance on using findings. */
+    /** Guidance on using findings (leaf agents). */
     private buildFindingsSection;
     /** MCP note (always included). */
     private buildMcpNote;

package/dist/system-prompt-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt-builder.d.ts","sourceRoot":"","sources":["../src/system-prompt-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,IAAI,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,uDAAuD;IACvD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;gBAE3B,OAAO,EAAE,mBAAmB;IAI/C,+CAA+C;IACxC,KAAK,IAAI,MAAM;IAsBtB,0CAA0C;IAC1C,OAAO,CAAC,gBAAgB;IAYxB,8CAA8C;IAC9C,OAAO,CAAC,uBAAuB;IAO/B,8CAA8C;IAC9C,OAAO,CAAC,mBAAmB;IAa3B,oCAAoC;IACpC,OAAO,CAAC,kBAAkB;IAU1B,kCAAkC;IAClC,OAAO,CAAC,oBAAoB;IAO5B,kCAAkC;IAClC,OAAO,CAAC,YAAY;CAGrB"}
+{"version":3,"file":"system-prompt-builder.d.ts","sourceRoot":"","sources":["../src/system-prompt-builder.ts"],"names":[],"mappings":"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"}