@corenel/harness 0.1.0 → 0.3.2

package/dist/sidecar/host.js

@@ -45,12 +45,107 @@ export class SidecarHost {
             writable: true,
             value: new Map()
         });
+        Object.defineProperty(this, "runSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "runPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "acpSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "acpPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "syncSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "syncPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "rootsSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "rootsPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "procSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "procPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /** Watchers by procId, NOT by request id: a process outlives the request that
+         * spawned it, and the same process can be watched by a spawn and later by a
+         * reattach. Keyed by the only durable identity there is. */
+        Object.defineProperty(this, "procWatchers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "sessionSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "sessionPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /** Per-session stream handlers, keyed by session because a session outlives
+         * the request that started watching it. */
+        Object.defineProperty(this, "sessionWatchers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         Object.defineProperty(this, "features", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: []
         });
+        Object.defineProperty(this, "info", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
         Object.defineProperty(this, "imported", {
             enumerable: true,
             configurable: true,
@@ -72,7 +167,12 @@ export class SidecarHost {
     connect() {
         return new Promise((resolve, reject) => {
             this.welcome = { resolve, reject };
-            this.ch.send({ t: 'hello', protocol: SIDECAR_PROTOCOL, token: this.opts.token });
+            this.ch.send({
+                t: 'hello', protocol: SIDECAR_PROTOCOL, token: this.opts.token,
+                ...(this.opts.stateDir ? { stateDir: this.opts.stateDir } : {}),
+                ...(this.opts.clientId ? { clientId: this.opts.clientId } : {}),
+                ...(this.opts.clientName ? { clientName: this.opts.clientName } : {}),
+            });
         });
     }
     /** Drop the connection: unregister imported tools and fail anything in flight. */
@@ -86,6 +186,32 @@ export class SidecarHost {
         for (const p of this.httpPending.values())
             p.onErr(reason);
         this.httpPending.clear();
+        for (const p of this.runPending.values())
+            p.reject(new Error(reason));
+        this.runPending.clear();
+        for (const p of this.acpPending.values())
+            p.reject(new Error(reason));
+        this.acpPending.clear();
+        for (const p of this.syncPending.values())
+            p.reject(new Error(reason));
+        this.syncPending.clear();
+        for (const p of this.rootsPending.values())
+            p.reject(new Error(reason));
+        this.rootsPending.clear();
+        /* Session and process calls settle too, and this was MISSING.
+         *
+         * Every other pending map was swept here and these two were not, so a
+         * `sessionPause` or `procStart` in flight when the daemon dropped never
+         * settled at all — not resolved, not rejected. A surface awaiting one sits
+         * on a disabled button reading "Starting…" until the page is reloaded,
+         * because the failure it is waiting to show never arrives. A dropped
+         * connection is an outcome; silence is not. */
+        for (const p of this.sessionPending.values())
+            p.reject(new Error(reason));
+        this.sessionPending.clear();
+        for (const p of this.procPending.values())
+            p.reject(new Error(reason));
+        this.procPending.clear();
         this.welcome?.reject(new Error(reason));
         this.welcome = null;
         this.ch.close();
@@ -94,6 +220,7 @@ export class SidecarHost {
         switch (m.t) {
             case 'welcome': {
                 this.features = m.features ?? [];
+                this.info = m.info ?? {};
                 for (const decl of m.tools) {
                     const tool = { ...decl, run: (args) => this.invoke(decl.name, args) };
                     this.opts.registerTool(tool);
@@ -119,6 +246,32 @@ export class SidecarHost {
                     p.reject(new Error(m.error || 'sidecar tool failed'));
                 return;
             }
+            case 'roots':
+                // Unsolicited: the set changed on the daemon (possibly via ANOTHER client).
+                this.opts.onRoots?.({ root: m.root, roots: m.roots });
+                return;
+            case 'roots-browse-result': {
+                const p = this.rootsPending.get(m.id);
+                if (!p)
+                    return;
+                this.rootsPending.delete(m.id);
+                if (m.ok)
+                    p.resolve(m.dirs ?? []);
+                else
+                    p.reject(new Error(m.error || 'could not browse'));
+                return;
+            }
+            case 'roots-add-result': {
+                const p = this.rootsPending.get(m.id);
+                if (!p)
+                    return;
+                this.rootsPending.delete(m.id);
+                if (m.ok)
+                    p.resolve([]);
+                else
+                    p.reject(new Error(m.error || 'could not add that working directory'));
+                return;
+            }
             case 'host-call':
                 void this.serveHostCall(m);
                 return;
@@ -138,12 +291,468 @@ export class SidecarHost {
                 this.httpPending.get(m.id)?.onErr(m.error);
                 return;
             }
+            case 'acp-started': {
+                const p = this.acpPending.get(m.id);
+                // The start call resolves, but the entry STAYS so later acp-update
+                // frames on this id still reach the caller's stream handler.
+                p?.resolve({
+                    runId: m.runId, sessionId: m.sessionId, agent: m.agent,
+                    ...(m.modes ? { modes: m.modes } : {}),
+                    ...(m.currentModeId ? { currentModeId: m.currentModeId } : {}),
+                    ...(m.resumed ? { resumed: true } : {}),
+                });
+                return;
+            }
+            case 'acp-mode-set': {
+                const p = this.acpPending.get(m.id);
+                this.acpPending.delete(m.id);
+                p?.resolve({ modeId: m.modeId });
+                return;
+            }
+            case 'acp-update':
+                this.acpPending.get(m.id)?.onUpdate?.(m.update);
+                return;
+            case 'acp-done': {
+                const p = this.acpPending.get(m.id);
+                this.acpPending.delete(m.id);
+                p?.resolve({ stopReason: m.stopReason });
+                return;
+            }
+            case 'acp-error': {
+                const p = this.acpPending.get(m.id);
+                this.acpPending.delete(m.id);
+                p?.reject(new Error(m.error));
+                return;
+            }
+            case 'run-accepted': {
+                const p = this.runPending.get(m.id);
+                if (p)
+                    p.runId = m.runId;
+                return;
+            }
+            case 'event': {
+                this.runPending.get(m.id)?.onEvent(m.event);
+                return;
+            }
+            case 'run-done': {
+                const p = this.runPending.get(m.id);
+                if (!p)
+                    return;
+                this.runPending.delete(m.id);
+                p.resolve({ runId: m.runId, text: m.text, stopReason: m.stopReason });
+                return;
+            }
+            case 'run-error': {
+                const p = this.runPending.get(m.id);
+                if (!p)
+                    return;
+                this.runPending.delete(m.id);
+                p.reject(new Error(m.error || 'run failed'));
+                return;
+            }
+            case 'host-sync-result': {
+                const p = this.syncPending.get(m.id);
+                if (!p)
+                    return;
+                this.syncPending.delete(m.id);
+                if (m.ok)
+                    p.resolve();
+                else
+                    p.reject(new Error(m.error || 'host sync failed'));
+                return;
+            }
+            case 'permission-ask': {
+                const { t: _t, ...ask } = m;
+                this.opts.onPermissionAsk?.(ask);
+                return;
+            }
+            case 'permission-resolved': {
+                this.opts.onPermissionResolved?.({ id: m.id, decision: m.decision, by: m.by });
+                return;
+            }
+            case 'run-activity': {
+                this.opts.onRunActivity?.(m.activity);
+                return;
+            }
+            case 'proc-started': {
+                const p = this.procPending.get(m.id);
+                if (!p)
+                    return;
+                this.procPending.delete(m.id);
+                p.resolve(m.proc);
+                return;
+            }
+            case 'proc-error': {
+                const p = this.procPending.get(m.id);
+                if (!p)
+                    return;
+                this.procPending.delete(m.id);
+                p.reject(new Error(m.error));
+                return;
+            }
+            case 'proc-attach-result':
+            case 'proc-kill-result':
+            case 'proc-input-result': {
+                const p = this.procPending.get(m.id);
+                if (!p)
+                    return;
+                this.procPending.delete(m.id);
+                if (m.ok)
+                    p.resolve(m);
+                else
+                    p.reject(new Error(m.error || 'process request failed'));
+                return;
+            }
+            case 'proc-list-result': {
+                const p = this.procPending.get(m.id);
+                if (!p)
+                    return;
+                this.procPending.delete(m.id);
+                p.resolve(m.procs);
+                return;
+            }
+            case 'proc-out': {
+                for (const w of this.procWatchers.get(m.procId) ?? [])
+                    w.onOut?.({ seq: m.seq, stream: m.stream, text: m.text });
+                return;
+            }
+            case 'proc-exit': {
+                const watchers = this.procWatchers.get(m.procId);
+                if (!watchers)
+                    return;
+                // Delete BEFORE notifying: an onExit that re-spawns and re-watches must
+                // not have its new registration wiped by this cleanup.
+                this.procWatchers.delete(m.procId);
+                for (const w of watchers)
+                    w.onExit?.({ code: m.code, ...(m.signal ? { signal: m.signal } : {}) });
+                return;
+            }
+            case 'session-list-result': {
+                const p = this.sessionPending.get(m.id);
+                if (!p)
+                    return;
+                this.sessionPending.delete(m.id);
+                p.resolve(m.sessions);
+                return;
+            }
+            case 'session-created': {
+                const p = this.sessionPending.get(m.id);
+                if (!p)
+                    return;
+                this.sessionPending.delete(m.id);
+                p.resolve(m.session);
+                return;
+            }
+            case 'session-paused': {
+                const p = this.sessionPending.get(m.id);
+                if (!p)
+                    return;
+                this.sessionPending.delete(m.id);
+                p.resolve({ drained: m.drained, remaining: m.remaining });
+                return;
+            }
+            case 'session-committed': {
+                const p = this.sessionPending.get(m.id);
+                if (!p)
+                    return;
+                this.sessionPending.delete(m.id);
+                p.resolve(m.snapshot);
+                return;
+            }
+            case 'run-transcript-result': {
+                const p = this.sessionPending.get(m.id);
+                if (!p)
+                    return;
+                this.sessionPending.delete(m.id);
+                p.resolve(m.lines);
+                return;
+            }
+            case 'run-history-result': {
+                const p = this.sessionPending.get(m.id);
+                if (!p)
+                    return;
+                this.sessionPending.delete(m.id);
+                p.resolve(m.runs);
+                return;
+            }
+            case 'session-snapshots-result': {
+                const p = this.sessionPending.get(m.id);
+                if (!p)
+                    return;
+                this.sessionPending.delete(m.id);
+                p.resolve(m.snapshots);
+                return;
+            }
+            case 'session-ok': {
+                const p = this.sessionPending.get(m.id);
+                if (!p)
+                    return;
+                this.sessionPending.delete(m.id);
+                p.resolve(undefined);
+                return;
+            }
+            case 'session-error': {
+                const p = this.sessionPending.get(m.id);
+                if (!p)
+                    return;
+                this.sessionPending.delete(m.id);
+                p.reject(new Error(m.error));
+                return;
+            }
+            case 'session-metrics': {
+                this.sessionWatchers.get(m.sessionId)?.onMetrics?.(m.sample);
+                return;
+            }
+            case 'session-log': {
+                this.sessionWatchers.get(m.sessionId)?.onLog?.(m.line);
+                return;
+            }
+            case 'registrations': {
+                this.opts.onRegistrations?.(m.registrations);
+                return;
+            }
             default:
                 return; // hello / invoke / host-call-result are handled on the sidecar side
         }
     }
     /** Whether the connected sidecar advertised the loopback HTTP proxy. */
     supportsHttpProxy() { return this.features.includes('http-proxy'); }
+    /** Everything the sidecar advertised. A copy — the internal list must not be
+     * mutable from outside. For surfaces that SHOW capabilities; code that DEPENDS
+     * on one should use the specific supportsX() so the feature name lives here. */
+    advertisedFeatures() { return [...this.features]; }
+    /** Whether the connected sidecar advertised a wired crew runner — i.e. it can
+     * actually fire daemon-tier triggers (schedule/continuous/self-directed) on its
+     * own clock, not just serve tools. */
+    supportsRunner() { return this.features.includes('runner'); }
+    /** True when the daemon was started with --acp and can proxy an external
+     * agent. A client must check this before offering the surface: a daemon
+     * without it answers acp-start with an error. */
+    supportsAcp() { return this.features.includes('acp'); }
+    /** True when the daemon can run long-lived processes - i.e. the operator
+     * allowed shell. A client MUST check this before offering the surface: a
+     * daemon without it answers every proc message with an error. */
+    supportsProcs() { return this.features.includes('procs'); }
+    /** Start a long-running command on the sidecar and stream its output.
+     *
+     * This is the counterpart to the one-shot `sidecar_shell_exec` tool, not a
+     * replacement: use the tool when you want the result of something that
+     * finishes, and this when you want to WATCH something that may not.
+     *
+     * The returned promise settles on the spawn, not on the exit - the process is
+     * still running when it resolves. `watch` keeps receiving output until
+     * `onExit`, which fires exactly once.
+     */
+    procSpawn(command, watch = {}, opts) {
+        const id = ++this.procSeq;
+        return new Promise((resolve, reject) => {
+            this.procPending.set(id, {
+                resolve: (v) => {
+                    const info = v;
+                    this.addProcWatcher(info.procId, watch);
+                    resolve(info);
+                },
+                reject,
+            });
+            this.ch.send({
+                t: 'proc-spawn', id, command,
+                ...(opts?.cwd ? { cwd: opts.cwd } : {}),
+                ...(opts?.root ? { root: opts.root } : {}),
+                ...(opts?.label ? { label: opts.label } : {}),
+            });
+        });
+    }
+    /** Re-attach to a process the daemon is already running - after a reload, or
+     * from a second tab. `sinceSeq` is the last chunk this client already has, so
+     * the replay is exactly the rest; omit it to replay the whole buffered tail.
+     *
+     * `truncated` in the result means the daemon's tail no longer reaches back to
+     * where you were: there is a GAP, and a UI that renders the replay as if it
+     * were continuous would be lying about what the process printed. */
+    procAttach(procId, watch = {}, sinceSeq) {
+        const id = ++this.procSeq;
+        return new Promise((resolve, reject) => {
+            this.procPending.set(id, {
+                // Register BEFORE resolving so output the daemon replays immediately
+                // after the result cannot arrive ahead of the watcher.
+                resolve: (v) => {
+                    const r = v;
+                    if (!r.proc) {
+                        reject(new Error('attach returned no process'));
+                        return;
+                    }
+                    this.addProcWatcher(procId, watch);
+                    resolve({ proc: r.proc, truncated: r.truncated === true });
+                },
+                reject,
+            });
+            this.ch.send({ t: 'proc-attach', id, procId, ...(sinceSeq === undefined ? {} : { sinceSeq }) });
+        });
+    }
+    /** Everything the daemon is running, or recently ran. Called on attach: a
+     * process nobody can see is worse than one that died. */
+    procList() {
+        const id = ++this.procSeq;
+        return new Promise((resolve, reject) => {
+            this.procPending.set(id, { resolve: (v) => resolve(v), reject });
+            this.ch.send({ t: 'proc-list', id });
+        });
+    }
+    /** Write to a running process's stdin. */
+    procInput(procId, text) {
+        const id = ++this.procSeq;
+        return new Promise((resolve, reject) => {
+            this.procPending.set(id, { resolve: () => resolve(), reject });
+            this.ch.send({ t: 'proc-input', id, procId, text });
+        });
+    }
+    /** Stop a process. Idempotent on the daemon side. */
+    procKill(procId) {
+        const id = ++this.procSeq;
+        return new Promise((resolve, reject) => {
+            this.procPending.set(id, { resolve: () => resolve(), reject });
+            this.ch.send({ t: 'proc-kill', id, procId });
+        });
+    }
+    /** Stop receiving a process's output without stopping the process. */
+    procUnwatch(procId, watch) {
+        const set = this.procWatchers.get(procId);
+        if (!set)
+            return;
+        set.delete(watch);
+        if (!set.size)
+            this.procWatchers.delete(procId);
+    }
+    addProcWatcher(procId, watch) {
+        const set = this.procWatchers.get(procId) ?? new Set();
+        set.add(watch);
+        this.procWatchers.set(procId, set);
+    }
+    /** True when the daemon runs sessions at all. A client MUST check this before
+     * offering the surface: a daemon without it answers every session message
+     * with an error. */
+    supportsSessions() { return this.features.includes('sessions'); }
+    /**
+     * Whether the OPERATOR allowed run transcripts to be kept at all.
+     *
+     * False means no run on this daemon can be recorded however it asks, so a
+     * surface must not offer the choice — a control that cannot be honoured is
+     * worse than an absent one. True does NOT mean recording is on: each run
+     * still opts in (`run(..., { keepTranscript: true })`).
+     */
+    supportsKeepTranscripts() { return this.features.includes('keep-transcripts'); }
+    /** Every session the daemon knows about. */
+    sessionList() {
+        return this.sessionCall((id) => ({ t: 'session-list', id }));
+    }
+    /**
+     * Create a session on a directory, or FROM a repository.
+     *
+     * Exactly one of `workdir` and `repo`. With `repo` the daemon clones on its
+     * own host, using its own git credentials, and mounts the result — which is
+     * why the caller cannot name the directory: it does not exist yet. The
+     * returned SessionInfo carries `source` with the resolved commit.
+     */
+    sessionCreate(spec) {
+        return this.sessionCall((id) => ({
+            t: 'session-create', id,
+            ...(spec.workdir ? { workdir: spec.workdir } : {}),
+            ...(spec.repo ? { repo: spec.repo } : {}),
+            ...(spec.owner ? { owner: spec.owner } : {}),
+            ...(spec.fromSnapshot ? { fromSnapshot: spec.fromSnapshot } : {}),
+        }));
+    }
+    /**
+     * Whether this daemon can create a session FROM a repository.
+     *
+     * False means the operator declared no `--clone-under` directory, so there is
+     * nowhere a checkout could be written and the option must not be offered.
+     */
+    supportsSessionClone() { return this.features.includes('session-clone'); }
+    /**
+     * Pause a session, and learn whether it actually drained.
+     *
+     * `drained: false` means work was STILL RUNNING when the wait gave up. A
+     * caller about to capture needs that: it is the difference between a snapshot
+     * and a torn one.
+     */
+    sessionPause(sessionId, drainMs) {
+        return this.sessionCall((id) => ({
+            t: 'session-pause', id, sessionId, ...(drainMs === undefined ? {} : { drainMs }),
+        }));
+    }
+    sessionResume(sessionId) {
+        return this.sessionCall((id) => ({ t: 'session-resume', id, sessionId }));
+    }
+    sessionDestroy(sessionId) {
+        return this.sessionCall((id) => ({ t: 'session-destroy', id, sessionId }));
+    }
+    sessionCommit(sessionId, name) {
+        return this.sessionCall((id) => ({
+            t: 'session-commit', id, sessionId, ...(name ? { name } : {}),
+        }));
+    }
+    /**
+     * One agent's finished runs, newest first, as the DAEMON recorded them.
+     *
+     * The durable counterpart to the live `run-activity` broadcasts: those say
+     * what is happening while this browser is attached and are lost on
+     * disconnect, this says what happened at all. Scoped to this client by the
+     * daemon, from the identity the connection authenticated with.
+     *
+     * An empty list means no record, which a caller renders rather than treats
+     * as an error — a daemon that keeps none is a normal daemon.
+     */
+    runHistory(agent, limit) {
+        return this.sessionCall((id) => ({
+            t: 'run-history', id, agent, ...(limit === undefined ? {} : { limit }),
+        }));
+    }
+    /**
+     * One run's kept events, as the daemon stored them.
+     *
+     * Empty means the words were never kept — the default, since transcripts are
+     * opt-in. A caller decides what to show from `RunRecordInfo.transcript`,
+     * which says whether there was ever anything to fetch.
+     */
+    runTranscript(agent, runId) {
+        return this.sessionCall((id) => ({ t: 'run-transcript', id, agent, runId }));
+    }
+    /** Every capture this daemon could restore from, newest first.
+     *
+     * An empty list is a real answer — a daemon whose backend cannot capture has
+     * nothing to restore from — so a caller uses the length to decide whether to
+     * offer the choice, not to detect a failure. */
+    sessionSnapshots() {
+        return this.sessionCall((id) => ({ t: 'session-snapshots', id }));
+    }
+    /** Start receiving a session's metrics and logs. */
+    async sessionWatch(sessionId, watch) {
+        // Registered BEFORE the request, so a sample that arrives immediately after
+        // the daemon starts following is not dropped on the floor.
+        this.sessionWatchers.set(sessionId, watch);
+        try {
+            await this.sessionCall((id) => ({ t: 'session-watch', id, sessionId }));
+        }
+        catch (e) {
+            this.sessionWatchers.delete(sessionId);
+            throw e;
+        }
+    }
+    async sessionUnwatch(sessionId) {
+        this.sessionWatchers.delete(sessionId);
+        await this.sessionCall((id) => ({ t: 'session-unwatch', id, sessionId }));
+    }
+    sessionCall(build) {
+        const id = ++this.sessionSeq;
+        return new Promise((resolve, reject) => {
+            this.sessionPending.set(id, { resolve, reject });
+            this.ch.send(build(id));
+        });
+    }
+    /** The sidecar's advertised self-description (root/platform), or {} if it sent
+     * none. Valid only after connect() resolves. */
+    sidecarInfo() { return this.info; }
     /** Fetch a (loopback) URL THROUGH the sidecar — a server-side fetch on the user's
      * machine, so the browser dodges CORS. Returns a streaming Response: it resolves
      * as soon as headers arrive (http-res) and the body streams in via http-chunk. */
@@ -177,6 +786,121 @@ export class SidecarHost {
             this.ch.send({ t: 'http-req', id, method: req.method, url: req.url, headers: req.headers, body: req.body });
         });
     }
+    /** Command the sidecar to run a crew agent, streaming its lifecycle events to
+     * `onEvent` as they arrive. Resolves once the run completes (`run-done`) with
+     * the daemon-assigned runId, final text, and stop reason; rejects on
+     * `run-error` or if the connection drops while the run is in flight. */
+    run(agent, input, onEvent, opts) {
+        const id = ++this.runSeq;
+        return new Promise((resolve, reject) => {
+            this.runPending.set(id, { resolve, reject, onEvent });
+            // `sessionId` asks for the run to happen INSIDE that session. A daemon
+            // that cannot honour it answers run-error rather than running it on the
+            // host, so the caller learns rather than being quietly downgraded.
+            // Sent only when asked for, so an unset option is indistinguishable on the
+            // wire from an older client that never had one — both mean keep nothing.
+            this.ch.send({
+                t: 'run', id, agent, input,
+                ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
+                ...(opts?.keepTranscript ? { keepTranscript: true } : {}),
+            });
+        });
+    }
+    /** Start a proxied external ACP agent on the sidecar. The returned promise
+     * settles on the handshake; `onUpdate` keeps receiving the agent's stream for
+     * the life of the session. Permission asks do NOT come through here — they use
+     * the existing permission-ask broadcast, the same path a crew run uses. */
+    acpStart(target, onUpdate, opts) {
+        const id = ++this.acpSeq;
+        return new Promise((resolve, reject) => {
+            this.acpPending.set(id, { resolve: resolve, reject, onUpdate });
+            // `root` is the working directory the USER has active. The daemon checks it
+            // against the operator's approved set and refuses anything else, so naming
+            // one here is a request, not a grant.
+            // `modeId` is a mode the user picked BEFORE a session existed - modes are
+            // only known after session/new, so an early choice has to be carried into
+            // the start rather than applied after it. `resume` asks the agent to
+            // reattach to a session it may or may not still hold.
+            this.ch.send({
+                t: 'acp-start', id, target,
+                ...(opts?.root ? { root: opts.root } : {}),
+                ...(opts?.modeId ? { modeId: opts.modeId } : {}),
+                ...(opts?.resume ? { resume: opts.resume } : {}),
+            });
+        });
+    }
+    /** Send one turn to the proxied agent. */
+    acpPrompt(text, content) {
+        const id = ++this.acpSeq;
+        return new Promise((resolve, reject) => {
+            this.acpPending.set(id, { resolve: resolve, reject });
+            this.ch.send({ t: 'acp-prompt', id, text, ...(content?.length ? { content: [...content] } : {}) });
+        });
+    }
+    /** Switch the proxied agent's mode. Rejects when it does not offer that mode. */
+    acpSetMode(modeId) {
+        const id = ++this.acpSeq;
+        return new Promise((resolve, reject) => {
+            this.acpPending.set(id, { resolve: resolve, reject });
+            this.ch.send({ t: 'acp-set-mode', id, modeId });
+        });
+    }
+    /** Interrupt the current turn. Fire-and-forget, like cancel in ACP itself. */
+    acpCancel() {
+        this.ch.send({ t: 'acp-cancel', id: ++this.acpSeq });
+    }
+    /** Answer an outstanding permission ask. Fire-and-forget over the wire — the
+     * actual drop of the prompt is driven by the server's `permission-resolved`
+     * broadcast (`onPermissionResolved`), not by this call returning. */
+    answerPermission(id, decision) {
+        this.ch.send({ t: 'permission-answer', id, decision });
+    }
+    /** Push one definition file's content to the daemon, to be persisted under
+     * this client's own `<stateDir>/hosts/<dirName>/` (Slice 2 host sync).
+     * Resolves on `host-sync-result { ok: true }`; rejects with the daemon's
+     * error, or on disconnect while in flight. */
+    hostSyncPut(path, content) {
+        const id = ++this.syncSeq;
+        return new Promise((resolve, reject) => {
+            this.syncPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'host-sync-put', id, path, content });
+        });
+    }
+    /** Delete one definition file on the daemon side (reconcile). Same
+     * resolve/reject contract as `hostSyncPut`. Callers are responsible for
+     * confining `path` to definition, non-state paths BEFORE calling this --
+     * this method has no opinion on what `path` is. */
+    hostSyncDelete(path) {
+        const id = ++this.syncSeq;
+        return new Promise((resolve, reject) => {
+            this.syncPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'host-sync-delete', id, path });
+        });
+    }
+    /** True when the operator started the sidecar with --allow-add-under, so a client
+     * may add a working directory this session. Feature-detected from the welcome --
+     * an older sidecar simply never advertises it. */
+    canAddRoots() { return this.features.includes('add-roots'); }
+    /** Directory NAMES under `path`, or the declared areas themselves when `path` is
+     * omitted. Names only: never files, contents or stats. Rejects with the sidecar's
+     * message (e.g. outside every allowed area). */
+    browseRoots(path) {
+        const id = ++this.rootsSeq;
+        return new Promise((resolve, reject) => {
+            this.rootsPending.set(id, { resolve, reject });
+            this.ch.send(path === undefined ? { t: 'roots-browse', id } : { t: 'roots-browse', id, path });
+        });
+    }
+    /** Promote `path` to a working directory for the rest of the session. Resolves on
+     * acceptance -- the resulting set arrives separately via `onRoots`, broadcast to
+     * every connected client -- and rejects with the sidecar's refusal message. */
+    async addRoot(path) {
+        const id = ++this.rootsSeq;
+        await new Promise((resolve, reject) => {
+            this.rootsPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'roots-add', id, path });
+        });
+    }
     invoke(name, args) {
         const id = ++this.invokeSeq;
         return new Promise((resolve, reject) => {