@khorsheed/dsh-local-agent 0.1.0-rc.6

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-local-agent`.
+ * @module @khorsheed/dsh-local-agent/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "local-agent-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - plugin context carrying the invariant registry.
+ * @returns the installed registration's disposer.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,105 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-local-agent`.
+ * @module @khorsheed/dsh-local-agent/invariant
+ */
+const PACKAGE_NAME = '@khorsheed/dsh-local-agent';
+/** Cordis companion plugin name. */
+export const name = 'local-agent-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+const NAME_PATTERN = /^[a-z][a-z0-9-]*$/u;
+/**
+ * Audit the harness registry lifecycle: a registered harness must carry a
+ * valid, unique command-prefix name, a home environment variable, and a
+ * records adapter, and a removed name must have been registered first.
+ */
+function auditLifecycle(ctx, fail) {
+    const known = new Set();
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName === 'localAgent/harness-added') {
+            const harness = args[0];
+            if (!NAME_PATTERN.test(harness.name)) {
+                fail(`localAgent/harness-added names a harness with invalid name ${JSON.stringify(harness.name)}`);
+            }
+            if (known.has(harness.name))
+                fail(`localAgent/harness-added repeats name ${JSON.stringify(harness.name)}`);
+            if (harness.homeEnvVar.length === 0)
+                fail(`localAgent/harness-added for ${harness.name} has an empty homeEnvVar`);
+            known.add(harness.name);
+            return;
+        }
+        if (eventName !== 'localAgent/harness-removed')
+            return;
+        const name = args[0];
+        if (!known.delete(name))
+            fail(`localAgent/harness-removed names unknown harness ${JSON.stringify(name)}`);
+    }, { global: true });
+}
+/**
+ * Cross-check delegation claims against the mounted subagent providers after
+ * the composition settles. A harness whose {@link LocalAgentHarness.delegationProvider}
+ * names a provider the tree does not mount means "identity present, delegation
+ * 404" — a typo in either the record or the bundle patch — and fails loud.
+ * A composition without the subagent seam (record-and-login only) skips the
+ * check; so does a harness without a delegation provider.
+ */
+async function auditDelegationClaims(ctx, fail) {
+    const loader = ctx.get('loader');
+    await loader?.await();
+    const subagents = ctx.get('subagents');
+    if (subagents === undefined)
+        return;
+    const registry = ctx.get('localAgent');
+    if (registry === undefined)
+        return;
+    for (const name of registry.list()) {
+        const providerName = registry.get(name)?.delegationProvider;
+        if (providerName === undefined)
+            continue;
+        if (subagents.getProvider(providerName) === undefined) {
+            fail(`local-agent harness ${name} declares delegation provider ${JSON.stringify(providerName)} which is not mounted`);
+        }
+    }
+}
+/**
+ * Audit the delegation registry: a recorded delegation must name a mounted
+ * subagent provider (the record is only useful when a resume round can route
+ * back through the same provider). Mirrors the harness-level delegation-claim
+ * check with the same "identity present, delegation 404" rationale — a record
+ * whose provider the tree does not mount means a provider rename left a stale
+ * mapping that would fail loud on the first resume attempt.
+ */
+async function auditDelegationProviders(ctx, fail) {
+    const loader = ctx.get('loader');
+    await loader?.await();
+    const subagents = ctx.get('subagents');
+    if (subagents === undefined)
+        return;
+    const registry = ctx.get('localAgent');
+    if (registry === undefined)
+        return;
+    for (const record of registry.listDelegations()) {
+        if (subagents.getProvider(record.provider) === undefined) {
+            fail(`local-agent delegation for child session ${record.childSessionId} records provider ${JSON.stringify(record.provider)} which is not mounted`);
+        }
+    }
+}
+/**
+ * Install the package's checks.
+ * @param ctx - child context owned by this invariant registration.
+ * @param fail - reporter bound to the registering package name.
+ */
+const install = Object.assign((ctx, fail) => {
+    auditLifecycle(ctx, fail);
+    return Promise.all([
+        auditDelegationClaims(ctx, fail),
+        auditDelegationProviders(ctx, fail),
+    ]).then(() => { });
+}, {});
+/**
+ * Register this package's invariant companion.
+ * @param ctx - plugin context carrying the invariant registry.
+ * @returns the installed registration's disposer.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */

package/lib/types/live-flush.d.ts

@@ -0,0 +1,21 @@
+/** Maximum batching delay for a live mirror; independent of persistence cadence. */
+export declare const LIVE_FLUSH_INTERVAL_MS = 50;
+/**
+ * Coalesce an item's updates without postponing its first pending deadline.
+ * Even a single short delta flushes without another provider event. Owners
+ * cancel an item before its authoritative final and dispose before turn/end.
+ */
+export declare class LiveFlush {
+    private readonly onError;
+    private readonly intervalMs;
+    private readonly pending;
+    private disposed;
+    constructor(onError: (error: unknown) => void, intervalMs?: number);
+    /** Schedule the latest content at the item's existing deadline. */
+    schedule(item: number, publish: () => void): void;
+    /** Supersede pending content with an authoritative final or immediate flush. */
+    cancel(item: number): void;
+    /** Retire every timer; a settled round must never publish a late snapshot. */
+    dispose(): void;
+}
+//# sourceMappingURL=live-flush.d.ts.map

package/lib/types/live-flush.js

@@ -0,0 +1,59 @@
+/** Maximum batching delay for a live mirror; independent of persistence cadence. */
+export const LIVE_FLUSH_INTERVAL_MS = 50;
+/**
+ * Coalesce an item's updates without postponing its first pending deadline.
+ * Even a single short delta flushes without another provider event. Owners
+ * cancel an item before its authoritative final and dispose before turn/end.
+ */
+export class LiveFlush {
+    onError;
+    intervalMs;
+    pending = new Map();
+    disposed = false;
+    constructor(onError, intervalMs = LIVE_FLUSH_INTERVAL_MS) {
+        this.onError = onError;
+        this.intervalMs = intervalMs;
+    }
+    /** Schedule the latest content at the item's existing deadline. */
+    schedule(item, publish) {
+        if (this.disposed)
+            return;
+        if (this.intervalMs <= 0) {
+            publish();
+            return;
+        }
+        const existing = this.pending.get(item);
+        if (existing !== undefined) {
+            existing.publish = publish;
+            return;
+        }
+        const entry = {
+            publish,
+            timer: setTimeout(() => {
+                this.pending.delete(item);
+                try {
+                    entry.publish();
+                }
+                catch (error) {
+                    this.onError(error);
+                }
+            }, this.intervalMs),
+        };
+        entry.timer.unref?.();
+        this.pending.set(item, entry);
+    }
+    /** Supersede pending content with an authoritative final or immediate flush. */
+    cancel(item) {
+        const entry = this.pending.get(item);
+        if (entry === undefined)
+            return;
+        clearTimeout(entry.timer);
+        this.pending.delete(item);
+    }
+    /** Retire every timer; a settled round must never publish a late snapshot. */
+    dispose() {
+        this.disposed = true;
+        for (const item of this.pending.keys())
+            this.cancel(item);
+    }
+}

package/lib/types/live-stream.d.ts

@@ -0,0 +1,41 @@
+/** Transient member output, with bounded followers and incremental durable checkpoints. */
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { LocalAgentStreamFrame, LocalAgentStreamItem } from './types.ts';
+/** Shared process-local output registry. No Agent impersonation or durable token events. */
+export declare class LocalAgentStreams {
+    private readonly items;
+    private readonly listeners;
+    private revision;
+    private disposed;
+    publish(sessionId: string, item: Omit<LocalAgentStreamItem, 'revision'>): void;
+    finish(sessionId: string, id: string): void;
+    private notify;
+    /**
+     * Opening baseline followed by coalesced suffix patches. Each follower keeps
+     * only its last delivered state; a slow browser cannot accumulate a queue.
+     */
+    follow(sessionId: string, signal: AbortSignal): AsyncIterable<LocalAgentStreamFrame>;
+    dispose(): void;
+}
+/** Durable cadence is independent of browser cadence; checkpoint bytes are suffixes. */
+export declare const LIVE_CHECKPOINT_INTERVAL_MS = 1000;
+/** One round's producer. Final native messages replace its presentation nodes by coordinate. */
+export declare class LiveStreamPublisher {
+    private readonly streams;
+    private readonly session;
+    private readonly turn;
+    private readonly persist;
+    private readonly onError;
+    private readonly states;
+    constructor(streams: LocalAgentStreams, session: Session, turn: number, persist: () => void, onError: (error: unknown) => void);
+    update(step: number, kind: 'think' | 'text', text: string, options?: {
+        itemId?: string;
+        receivedAt?: number;
+    }): void;
+    private checkpoint;
+    /** Call only after the corresponding native final message has been appended. */
+    finish(step: number): void;
+    /** A producer failure keeps a durable partial, without claiming completion. */
+    dispose(): void;
+}
+//# sourceMappingURL=live-stream.d.ts.map

package/lib/types/live-stream.js

@@ -0,0 +1,178 @@
+/** Shared process-local output registry. No Agent impersonation or durable token events. */
+export class LocalAgentStreams {
+    items = new Map();
+    listeners = new Map();
+    revision = 0;
+    disposed = false;
+    publish(sessionId, item) {
+        if (this.disposed)
+            return;
+        let items = this.items.get(sessionId);
+        if (items === undefined)
+            this.items.set(sessionId, items = new Map());
+        items.set(item.id, { ...item, revision: ++this.revision });
+        this.notify(sessionId);
+    }
+    finish(sessionId, id) {
+        const items = this.items.get(sessionId);
+        if (!items?.delete(id))
+            return;
+        if (items.size === 0)
+            this.items.delete(sessionId);
+        this.notify(sessionId);
+    }
+    notify(sessionId) {
+        for (const listener of this.listeners.get(sessionId) ?? [])
+            listener();
+    }
+    /**
+     * Opening baseline followed by coalesced suffix patches. Each follower keeps
+     * only its last delivered state; a slow browser cannot accumulate a queue.
+     */
+    async *follow(sessionId, signal) {
+        let wake;
+        let dirty = true;
+        let baseline = true;
+        const previous = new Map();
+        const notify = () => { dirty = true; wake?.(); wake = undefined; };
+        let listeners = this.listeners.get(sessionId);
+        if (listeners === undefined)
+            this.listeners.set(sessionId, listeners = new Set());
+        listeners.add(notify);
+        signal.addEventListener('abort', notify, { once: true });
+        try {
+            while (!signal.aborted && !this.disposed) {
+                if (!dirty)
+                    await new Promise(resolve => { wake = resolve; });
+                if (signal.aborted || this.disposed)
+                    return;
+                dirty = false;
+                const items = this.items.get(sessionId) ?? new Map();
+                const updates = [];
+                const removed = [];
+                for (const [id, item] of items) {
+                    const old = previous.get(id);
+                    if (old?.revision === item.revision)
+                        continue;
+                    const append = old !== undefined && item.text.startsWith(old.text);
+                    updates.push({ ...item, text: append ? item.text.slice(old.text.length) : item.text, append });
+                    previous.set(id, item);
+                }
+                for (const id of previous.keys()) {
+                    if (!items.has(id)) {
+                        previous.delete(id);
+                        removed.push(id);
+                    }
+                }
+                if (baseline || updates.length > 0 || removed.length > 0) {
+                    const frame = { baseline, updates, removed };
+                    baseline = false;
+                    yield frame;
+                }
+            }
+        }
+        finally {
+            signal.removeEventListener('abort', notify);
+            listeners.delete(notify);
+            if (listeners.size === 0)
+                this.listeners.delete(sessionId);
+        }
+    }
+    dispose() {
+        this.disposed = true;
+        this.items.clear();
+        for (const listeners of this.listeners.values())
+            for (const notify of listeners)
+                notify();
+        this.listeners.clear();
+    }
+}
+/** Durable cadence is independent of browser cadence; checkpoint bytes are suffixes. */
+export const LIVE_CHECKPOINT_INTERVAL_MS = 1_000;
+/** One round's producer. Final native messages replace its presentation nodes by coordinate. */
+export class LiveStreamPublisher {
+    streams;
+    session;
+    turn;
+    persist;
+    onError;
+    states = new Map();
+    constructor(streams, session, turn, persist, onError) {
+        this.streams = streams;
+        this.session = session;
+        this.turn = turn;
+        this.persist = persist;
+        this.onError = onError;
+    }
+    update(step, kind, text, options = {}) {
+        const id = `${this.turn}:${step}${options.itemId === undefined ? '' : `:${options.itemId}`}`;
+        let state = this.states.get(id);
+        if (state?.item.text === text && state.item.kind === kind)
+            return;
+        const receivedAt = options.receivedAt ?? Date.now();
+        if (state === undefined) {
+            const item = { id, turn: this.turn, step, kind, text, receivedAt };
+            state = { item, durable: text };
+            this.states.set(id, state);
+            this.session.append('local-agent/stream', { ...item, sessionId: String(this.session.id), opening: true, append: false });
+            this.persist();
+        }
+        else {
+            state.item = { ...state.item, kind, text, receivedAt };
+        }
+        this.streams.publish(String(this.session.id), state.item);
+        if (state.timer === undefined) {
+            state.timer = setTimeout(() => {
+                delete state.timer;
+                try {
+                    this.checkpoint(id);
+                }
+                catch (error) {
+                    this.onError(error);
+                }
+            }, LIVE_CHECKPOINT_INTERVAL_MS);
+            state.timer.unref?.();
+        }
+    }
+    checkpoint(id) {
+        const state = this.states.get(id);
+        if (state === undefined || state.durable === state.item.text)
+            return;
+        const append = state.item.text.startsWith(state.durable);
+        this.session.append('local-agent/stream', {
+            ...state.item,
+            sessionId: String(this.session.id),
+            text: append ? state.item.text.slice(state.durable.length) : state.item.text,
+            append,
+        });
+        state.durable = state.item.text;
+        this.persist();
+    }
+    /** Call only after the corresponding native final message has been appended. */
+    finish(step) {
+        for (const [id, state] of this.states) {
+            if (state.item.step !== step)
+                continue;
+            if (state.timer !== undefined)
+                clearTimeout(state.timer);
+            // Native final events identify the whole step. Subitems additionally
+            // close their own anchors so replay cannot resurrect a duplicate block.
+            if (id !== `${this.turn}:${step}`) {
+                this.session.append('local-agent/stream', { ...state.item, sessionId: String(this.session.id), text: '', append: true, closed: true });
+                this.persist();
+            }
+            this.states.delete(id);
+            this.streams.finish(String(this.session.id), id);
+        }
+    }
+    /** A producer failure keeps a durable partial, without claiming completion. */
+    dispose() {
+        for (const [id, state] of this.states) {
+            this.checkpoint(id);
+            if (state.timer !== undefined)
+                clearTimeout(state.timer);
+            this.streams.finish(String(this.session.id), id);
+        }
+        this.states.clear();
+    }
+}

package/lib/types/member-bridge.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Member bridge: a minimal standalone MCP server (stdio, newline-delimited
+ * JSON-RPC) exposing member messaging and room coordination tools to the CLI
+ * member that spawned it. Each call is forwarded to the host's member-channel
+ * listener over the loopback socket named by `DSH_MEMBER_SOCKET`,
+ * authenticated by the per-run token in `DSH_MEMBER_TOKEN`; the host's
+ * receipt is the tool result verbatim.
+ *
+ * The process is dependency-free (node builtins only) because the CLI spawns
+ * it bare: `node <this file>`, with the socket path and token in its
+ * environment (written into the CLI's scoped MCP config by the provider).
+ * Covers the MCP handshake subset a client needs: `initialize`,
+ * `notifications/initialized`, `ping`, `tools/list`, `tools/call`.
+ * @module @khorsheed/dsh-local-agent/member-bridge
+ */
+import type { Readable, Writable } from 'node:stream';
+import type { MemberRoomCommandName } from './types.ts';
+/** The one tool this server exposes. */
+export declare const MEMBER_MESSAGE_TOOL = "member_message";
+export declare function callRoomCommand(env: MemberBridgeEnv, name: MemberRoomCommandName, args: unknown): Promise<Record<string, unknown>>;
+/** What the bridge needs from its environment (injectable for tests). */
+export interface MemberBridgeEnv {
+    /** Host member-channel socket path. */
+    readonly socket?: string | undefined;
+    /** This run's member-channel token. */
+    readonly token?: string | undefined;
+}
+/**
+ * Handle one `member_message` tool call: forward to the host listener and map
+ * the outcome to a tool result. Channel failures (missing env, unreachable
+ * listener, rejected token) are tool errors; delivery verdicts are text.
+ * @param env - the bridge's environment (socket, token).
+ * @param args - the tool arguments (`to`, `text`).
+ * @returns the MCP tool result object.
+ */
+export declare function callMemberMessage(env: MemberBridgeEnv, args: {
+    to?: unknown;
+    text?: unknown;
+}): Promise<Record<string, unknown>>;
+/**
+ * Run the stdio JSON-RPC loop over the given streams (injectable for tests).
+ * Unknown methods with an id get a MethodNotFound error; notifications are
+ * ignored. Never throws — a malformed line is answered with a parse error and
+ * the loop continues.
+ * @param env - the bridge's environment.
+ * @param input - the stdin side.
+ * @param output - the stdout side.
+ */
+export declare function serveMemberBridge(env: MemberBridgeEnv, input: Readable, output: Writable): void;
+//# sourceMappingURL=member-bridge.d.ts.map