deepclause-sdk 0.1.3 → 0.2.2

package/dist/repl/session.js

@@ -13,16 +13,103 @@ import { loadProlog, mountWorkspace, takePrologMessages, } from '../prolog/loade
 import { describeShellExecutionBackend, } from '../system/runtime/shell-manager.js';
 import { getWorkspaceDocAssetPath } from '../system/assets/index.js';
 import { DMLRunner, toJsValue } from '../runner.js';
+import { DmlProcessExecutor } from './process-executor.js';
+import { pidKey } from './processes.js';
 import { compactMemory, estimateMemoryTokens, shouldCompact, toCompactionEvent, } from './compaction.js';
 import { HarnessAgent } from './agent.js';
 import { BRIEF_VALUE_CHARS, createHarnessTools } from './harness-tools.js';
 import { buildParamsTerm, plainValue, quotePrologString } from './frames.js';
 import { buildHarnessHeader, } from './export.js';
-import { HistoryStore, harnessHash, } from './history.js';
+import { HistoryStore, harnessHash, moduleVersion, } from './history.js';
 import { buildDiagramPrompt, extractMermaid, parseMermaidFlowchart, rasterizeSvg, renderFlowchartSvg, renderMermaidAscii, resolveMedia, validateMermaid, } from '../visualize/index.js';
 import { generateLlmReply } from '../prolog/bridge.js';
 import { formatModelCatalogEntry } from './model-resolver.js';
+/**
+ * Context note added when a saved session is reloaded. The opening words are
+ * also the de-duplication marker in `repl_note_resumed/2` — keep them in sync.
+ */
+const RESUME_NOTE = 'This session was reloaded from a saved snapshot and its transient state was reset: '
+    + 'the harness and conversation memory were restored, but any subagents/services running '
+    + 'before are gone. Re-create anything you still need.';
+const RESUME_NOTE_PREFIX = 'This session was reloaded';
 let sessionCounter = 0;
+/**
+ * One human, one editor: human-channel requests from the foreground and from any
+ * subagent are served strictly in order (see `requireInput`).
+ */
+let sharedInputQueue = Promise.resolve();
+/** Rebuild a `DMLEvent` from a persisted history record, or undefined. */
+function historyEventFromRecord(record) {
+    const type = typeof record.type === 'string' ? record.type : undefined;
+    if (!type)
+        return undefined;
+    const frameKind = typeof record.frame === 'string' ? record.frame : undefined;
+    const content = typeof record.content === 'string' ? record.content : undefined;
+    switch (type) {
+        case 'stream':
+            return content ? { type, frameKind, content } : undefined;
+        case 'output':
+        case 'answer':
+        case 'error':
+            return { type, frameKind, content };
+        case 'log':
+            return { type, frameKind, content, level: record.level };
+        case 'tool_call':
+            return {
+                type,
+                frameKind,
+                toolName: typeof record.toolName === 'string' ? record.toolName : undefined,
+                toolState: record.toolState,
+                toolSummary: typeof record.toolSummary === 'string' ? record.toolSummary : undefined,
+                toolArgs: record.toolArgs,
+            };
+        case 'solution':
+            return {
+                type,
+                frameKind,
+                solution: {
+                    bindings: (Array.isArray(record.bindings) ? record.bindings : []),
+                    deterministic: false,
+                },
+            };
+        case 'task_activity':
+            return {
+                type,
+                frameKind,
+                taskState: record.taskState,
+                taskDescription: typeof record.taskDescription === 'string' ? record.taskDescription : undefined,
+            };
+        default:
+            return undefined;
+    }
+}
+/** The log-view line for an event, or undefined for per-tick noise. */
+function processLogText(event) {
+    switch (event.type) {
+        case 'started':
+            return 'started';
+        case 'output':
+        case 'stream':
+        case 'reasoning':
+        case 'tool':
+        case 'model':
+            return event.content ?? '';
+        case 'answer': {
+            // A process's terminal result is its accumulated output; the actual
+            // answer/1 value is the last non-empty line, so use that (and avoid
+            // duplicating the whole transcript in one log row).
+            const text = String(event.answer ?? 'ok');
+            const lines = text.split('\n').map((line) => line.trim()).filter(Boolean);
+            return `› ${lines.length > 0 ? lines[lines.length - 1] : text}`;
+        }
+        case 'exited':
+            if (event.state === 'done')
+                return 'finished';
+            return `${event.state}${event.error ? ` (${event.error})` : event.reason && event.reason !== 'normal' ? ` (${String(event.reason)})` : ''}`;
+        default:
+            return undefined; // state/activity are shown in the summary view
+    }
+}
 function nextSessionId() {
     sessionCounter += 1;
     return `repl_${Date.now().toString(36)}_${sessionCounter}`;
@@ -83,6 +170,23 @@ export class DMLSession {
     /** Full resolution for the backend, for the agent's environment block. */
     executionEnvironment;
     autoLoadHarness;
+    /** Original options, used to create per-process child sessions. */
+    openOptions;
+    /** Session-scoped subagents (spec §2). */
+    processBackend;
+    processBackendPromise;
+    /**
+     * The harness snapshot new processes should run. On the main session this is
+     * unset (children snapshot the live module); a worker host sets it to the
+     * snapshot the main sent, so its children never run a stale module.
+     */
+    processSnapshot;
+    processEventSink;
+    /** Bounded log of subagent output for the `/ps --watch --logs` view. */
+    processLogEntries = [];
+    static PROCESS_LOG_LIMIT = 500;
+    /** Service declarations replayed from the session record (resume only). */
+    recordedServices = [];
     /** Monotonic per-session turn counter used by history records. */
     turnCounter = 0;
     historyWarned = false;
@@ -109,6 +213,7 @@ export class DMLSession {
         this.executionBackend = options.executionBackend ?? 'clean-room';
         this.executionEnvironment = describeShellExecutionBackend(this.executionBackend === 'agentvm', this.executionBackend === 'agentvm' ? {} : { wrapper: this.executionBackend });
         this.autoLoadHarness = options.autoLoadHarness ?? true;
+        this.openOptions = options;
         this.compactionSettings = options.compaction?.settings;
         this.compactionAuto = options.compaction?.auto ?? false;
         this.contextWindow = options.contextWindow;
@@ -144,6 +249,7 @@ export class DMLSession {
             }
             const store = new HistoryStore(options.workspacePath ?? process.cwd(), session.sessionId, options.history, session.harnessName);
             snapshot = await store.readSessionHarness();
+            session.recordedServices = await store.readServiceRecords();
             if (!snapshot) {
                 throw new Error(`session not found or has no saved harness: ${session.sessionId}`);
             }
@@ -174,6 +280,7 @@ export class DMLSession {
                 session.agentMessages = snapshot.memory.agent;
             }
             await session.restoreHarnessFromHistory(snapshot);
+            session.noteSessionResumed();
         }
         else if (session.autoLoadHarness) {
             // One harness per name: a fresh session starts from the harness's current
@@ -191,6 +298,299 @@ export class DMLSession {
     getSessionId() {
         return this.sessionId;
     }
+    /**
+     * The live harness, for the side view: what predicates exist right now, how big
+     * each is, and what the open transaction has touched.
+     *
+     * Read from the session module rather than from the last commit, so a side view
+     * shows the harness *being built* — including uncommitted edits.
+     */
+    harnessView() {
+        const result = this.prologQuery(`deepclause_mi:repl_harness_view('${this.sessionId}', Rows)`);
+        const raw = toJsValue(result?.Rows);
+        const predicates = Array.isArray(raw)
+            ? raw
+                .map((row) => String(row).split('|'))
+                .filter((parts) => parts.length === 3)
+                .map(([indicator, clauses, flags]) => {
+                const [name, arityText] = indicator.split('/');
+                return {
+                    indicator: indicator.trim(),
+                    name: String(name).trim(),
+                    arity: Number(arityText),
+                    clauses: Number(clauses),
+                    flags: String(flags).split(',').map((flag) => flag.trim()).filter(Boolean),
+                };
+            })
+            : [];
+        const versionResult = this.prologQuery(`( current_predicate(${this.sessionId}:harness_head/4)`
+            + ` -> ${this.sessionId}:harness_head(V, _, _, _) ; V = none )`);
+        const version = plainValue(versionResult?.V);
+        return {
+            predicates: predicates.sort((a, b) => a.indicator.localeCompare(b.indicator)),
+            version: version === 'none' ? undefined : Number(version),
+            transactionOpen: this.transactionBefore !== null,
+            touched: this.editTouched(),
+            lastCommit: this.lastTurnCommitted,
+        };
+    }
+    // ---- Session-scoped subagents (spec §2) --------------------------------
+    /** Register the sink that receives process lifecycle and output events. */
+    setProcessEventSink(sink) {
+        this.processEventSink = sink;
+    }
+    /**
+     * The process backend: in-process (L1) or worker-backed (L2). Created lazily
+     * so a session with no subagents pays nothing.
+     */
+    ensureProcessBackend() {
+        if (this.processBackendPromise)
+            return this.processBackendPromise;
+        const mode = this.openOptions.execution ?? 'worker';
+        this.processBackendPromise = (async () => {
+            const onEvent = (event) => {
+                this.processEventSink?.(event);
+                this.recordServiceEvent(event);
+            };
+            if (mode === 'worker') {
+                const { RemoteProcessHost } = await import('./worker-host.js');
+                const host = new RemoteProcessHost(this, { onEvent });
+                await host.start();
+                this.processBackend = host;
+                return host;
+            }
+            const executor = new DmlProcessExecutor(this, { onEvent });
+            this.processBackend = executor;
+            return executor;
+        })();
+        return this.processBackendPromise;
+    }
+    /** Record a process declaration/exit so a resumed session can replay it (§7). */
+    recordServiceEvent(event) {
+        this.recordProcessLog(event);
+        if (!this.history)
+            return;
+        if (event.type === 'started') {
+            const info = this.processBackend?.info(event.pid);
+            void this.history.appendServiceRecord({
+                type: 'declare',
+                at: event.at,
+                pid: event.pid,
+                name: event.name,
+                goal: info?.goal,
+                priority: info?.priority,
+                codeVersion: info?.codeVersion,
+                harnessVersion: info?.harnessVersion,
+            });
+        }
+        else if (event.type === 'exited') {
+            void this.history.appendServiceRecord({
+                type: 'exit',
+                at: event.at,
+                pid: event.pid,
+                name: event.name,
+                state: event.state,
+                reason: event.reason,
+            });
+        }
+    }
+    /** Service declarations replayed from the session record (resume only). */
+    recordedProcesses() {
+        return this.recordedServices;
+    }
+    /**
+     * Recent subagent output for the log view, oldest first. Answers and exits are
+     * included; per-tick state/activity updates are not (the summary shows those).
+     */
+    processLog(limit = 200) {
+        const entries = this.processLogEntries;
+        return limit >= entries.length ? [...entries] : entries.slice(entries.length - limit);
+    }
+    /**
+     * Events from the resumed session, to render it on load. Empty unless this
+     * session was opened with `resume` and history is enabled.
+     */
+    async resumedTranscript(limit = 400) {
+        if (!this.resume || !this.history)
+            return [];
+        const records = await this.history.readEvents(this.sessionId, limit);
+        return records
+            .map((record) => historyEventFromRecord(record))
+            .filter((event) => Boolean(event));
+    }
+    recordProcessLog(event) {
+        const text = processLogText(event);
+        if (text === undefined)
+            return;
+        // Coalesce streamed chunks into one growing line per process/kind.
+        const last = this.processLogEntries[this.processLogEntries.length - 1];
+        const streamy = event.type === 'stream' || event.type === 'reasoning';
+        if (streamy && last && last.kind === event.type && pidKey(last.pid) === pidKey(event.pid) && !last.done) {
+            last.text = (last.text + text).slice(-2000);
+            last.done = event.done;
+            return;
+        }
+        this.processLogEntries.push({
+            at: event.at,
+            pid: event.pid,
+            name: event.name,
+            kind: event.type,
+            text,
+            done: event.done,
+        });
+        if (this.processLogEntries.length > DMLSession.PROCESS_LOG_LIMIT) {
+            this.processLogEntries.splice(0, this.processLogEntries.length - DMLSession.PROCESS_LOG_LIMIT);
+        }
+    }
+    /** Start a session-scoped subagent running `goal`; returns immediately. */
+    async spawnProcess(goal, options = {}) {
+        return (await this.ensureProcessBackend()).spawn(goal, options);
+    }
+    /** The whole system state: every process this session owns. */
+    processes() {
+        return this.processBackend?.processes() ?? [];
+    }
+    processInfo(pid) {
+        return this.processBackend?.info(pid);
+    }
+    /**
+     * The harness source a process is running, for inspection. Accepts a pid or a
+     * registered name. Undefined when the process is unknown.
+     */
+    processCode(target) {
+        const pid = typeof target === 'string' ? this.processBackend?.whereis(target) : target;
+        return pid ? this.processBackend?.codeOf(pid) : undefined;
+    }
+    /** The version of the harness the session itself is currently editing. */
+    currentHarnessVersion() {
+        return this.processSnapshotFor().version;
+    }
+    /** Stop one process by pid or registered name. */
+    async stopProcess(target, reason = 'shutdown') {
+        await (await this.ensureProcessBackend()).stop(target, reason);
+    }
+    /** Resolve a registered process name. */
+    whereisProcess(name) {
+        return this.processBackend?.whereis(name);
+    }
+    /** Register a process under a session-scoped name. */
+    registerProcess(name, pid) {
+        this.processBackend?.register(name, pid);
+    }
+    /** Copy a message term into a process's mailbox. */
+    sendProcess(to, messageTerm) {
+        this.processBackend?.send(to, messageTerm);
+    }
+    /** Request/reply against a service process (library(service) protocol). */
+    async callProcess(to, messageTerm, timeoutMs = 300_000) {
+        return (await this.ensureProcessBackend()).callTerm(to, messageTerm, timeoutMs);
+    }
+    /** Resolve a process primitive for this (non-process) foreground run. */
+    async handleForeground(request, signal) {
+        return (await this.ensureProcessBackend()).foregroundHandle(request, signal);
+    }
+    /** Host tool descriptors, for a worker's proxy tools. */
+    toolDescriptors() {
+        return [...this.tools.entries()].map(([name, tool]) => ({
+            name,
+            description: tool.description,
+            parameters: tool.parameters,
+        }));
+    }
+    /** Run a model call on behalf of a worker's proxy backend. */
+    async completeModelRequest(request) {
+        if (!this.llmBackend)
+            throw new Error('this session has no LLM backend');
+        return this.llmBackend.complete(request);
+    }
+    /** Run a host tool on behalf of a worker's proxy tool. */
+    runHostTool(name, args, signal) {
+        const tool = this.tools.get(name);
+        if (!tool)
+            throw new Error(`unknown host tool: ${name}`);
+        return tool.execute(args, { signal });
+    }
+    /** Prompt the human on behalf of a worker's `input/2`. */
+    requestHumanInput(prompt) {
+        return this.requireInput(prompt);
+    }
+    // Accessors for building a worker's init data (see worker-host.ts).
+    workspacePathValue() {
+        return this.workspacePath;
+    }
+    modelId() {
+        return this.model;
+    }
+    providerId() {
+        return this.provider;
+    }
+    temperatureValue() {
+        return this.temperature;
+    }
+    maxTokensValue() {
+        return this.maxTokens;
+    }
+    toolPolicyValue() {
+        return this.toolPolicy;
+    }
+    /** The living module as loadable DML source, for a process snapshot. */
+    async harnessText() {
+        return this.harnessTextSync();
+    }
+    /** Synchronous form of `harnessText`, for spawn-time stamping. */
+    harnessTextSync() {
+        const result = this.prologQuery(`deepclause_mi:export_harness('${this.sessionId}', '', Text)`);
+        return String(plainValue(result?.Text) ?? '');
+    }
+    /**
+     * The harness snapshot and its version for a process about to be spawned.
+     *
+     * A worker host holds the snapshot the main sent; the main computes it from
+     * the live module. Either way, every process carries the exact module it runs
+     * and a version that lets two processes be compared at a glance.
+     */
+    processSnapshotFor() {
+        if (this.processSnapshot)
+            return this.processSnapshot;
+        const text = this.harnessTextSync();
+        return { text, version: moduleVersion(text) };
+    }
+    /**
+     * Adopt a process snapshot pushed by the main session (worker hosts only).
+     * Keeps a worker's children on the code the user actually committed.
+     */
+    setProcessSnapshot(text, version) {
+        this.processSnapshot = { text, version: version ?? moduleVersion(text) };
+    }
+    /**
+     * A private child session carrying a snapshot of this harness (invariant C).
+     *
+     * Returns the session and, when the snapshot could not be loaded, the load
+     * error. It does **not** throw on a load failure: the child still runs its goal
+     * (a swarm item reports `failed`, say), whereas throwing would kill the process
+     * before it can report and leave a waiting parent hanging.
+     */
+    async createProcessSession() {
+        const text = this.processSnapshotFor().text;
+        const child = await DMLSession.open({
+            ...this.openOptions,
+            execution: 'inline',
+            sessionId: undefined,
+            resume: false,
+            history: undefined,
+            autoLoadHarness: false,
+            tools: this.tools,
+            toolPolicy: this.toolPolicy,
+            onInput: this.inputHandler,
+            onInputRequired: undefined,
+        });
+        let loadError;
+        if (text.trim()) {
+            const loaded = await child.loadCode(text);
+            loadError = loaded.error;
+        }
+        return { session: child, loadError };
+    }
     /**
      * Prolog output captured since the last drain.
      *
@@ -301,6 +701,19 @@ export class DMLSession {
             this.warnHistory(error);
         }
     }
+    /**
+     * Note in the model's context that this session was restored. Without it an
+     * agent can assume work from a previous run is still alive — a subagent, a
+     * service, an in-flight job — when the runtime state is gone. The note is
+     * replaced (not stacked) across repeated resumes.
+     */
+    noteSessionResumed() {
+        this.prologQuery(`deepclause_mi:repl_note_resumed('${this.sessionId}', ${quoteString(RESUME_NOTE)})`);
+        this.agentMessages = [
+            ...this.agentMessages.filter((message) => !message.content.startsWith(RESUME_NOTE_PREFIX)),
+            { role: 'system', content: RESUME_NOTE },
+        ];
+    }
     /**
      * Restore a resumed session's harness from its durable snapshot and continue
      * its turn numbering. The saved module is a restore, not a user load, so it
@@ -783,7 +1196,7 @@ export class DMLSession {
      * The child frame uses the living scratch module and may itself call task()
      * (RLM-style recursion); its harness-memory writes are discarded afterward.
      */
-    async executeGoal(goal, limit = 5, onEvent, signal, bindingMode = 'full') {
+    async executeGoal(goal, limit = 5, onEvent, signal, bindingMode = 'full', process) {
         const startedAt = Date.now();
         const elapsed = () => Date.now() - startedAt;
         const childDepth = this.frameDepth + 1;
@@ -814,7 +1227,7 @@ export class DMLSession {
         let runError;
         this.frameDepth = childDepth;
         try {
-            for await (const event of this.runner.runFrame(frame.id, this.buildRunOptions({ signal }))) {
+            for await (const event of this.runner.runFrame(frame.id, this.buildRunOptions({ signal, process }))) {
                 onEvent?.(event);
                 if (event.type === 'solution') {
                     if (solutions.length < limit) {
@@ -1359,6 +1772,14 @@ export class DMLSession {
         if (this.disposed)
             return;
         this.disposed = true;
+        if (this.processBackend) {
+            try {
+                await this.processBackend.shutdown();
+            }
+            catch {
+                // teardown is best-effort
+            }
+        }
         if (this.history) {
             try {
                 await this.persistSessionHarness(this.history.currentVersion);
@@ -1384,6 +1805,11 @@ export class DMLSession {
                 : async () => undefined,
             signal: options.signal,
             onModelCall: () => this.reserveModelCall(),
+            // A run that is not itself a process resolves primitives through the
+            // process backend (local or worker); a process uses its own binding.
+            onProcessRequest: options.process
+                ? (request, signal) => options.process.handle(request, signal)
+                : (request, signal) => this.handleForeground(request, signal),
         };
     }
     // ---- TypeScript compaction (ported from pi) ----
@@ -1511,7 +1937,12 @@ export class DMLSession {
         if (!this.inputHandler) {
             return undefined;
         }
-        return this.inputHandler(prompt, options);
+        // Serialize human-channel requests across every session in this process: a
+        // background subagent's input/2 must not clobber a foreground prompt (one
+        // editor, one human). Child process sessions share this module-level queue.
+        const value = sharedInputQueue.then(() => this.inputHandler(prompt, options));
+        sharedInputQueue = value.then(() => undefined, () => undefined);
+        return value;
     }
     /**
      * Reserve one model call for the current turn. When the budget is reached,