@corenel/harness 0.10.0 → 0.12.0

package/dist/sidecar/host.js

@@ -1,4 +1,4 @@
-import { SIDECAR_PROTOCOL, HOST_METHODS, errMessage, } from '@corenel/protocol';
+import { SIDECAR_PROTOCOL, HOST_METHODS, errMessage, RUN_TASK_FEATURE, RUN_PLAN_FEATURE, CREW_DEPLOY_FEATURE, } from '@corenel/protocol';
 /** Decode a base64 chunk to bytes (atob is available in the browser and Node 18+). */
 function b64ToBytes(b64) {
     const bin = atob(b64);
@@ -57,6 +57,18 @@ export class SidecarHost {
             writable: true,
             value: new Map()
         });
+        Object.defineProperty(this, "cancelSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "cancelPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         Object.defineProperty(this, "acpSeq", {
             enumerable: true,
             configurable: true,
@@ -162,6 +174,60 @@ export class SidecarHost {
             writable: true,
             value: new Map()
         });
+        Object.defineProperty(this, "crewDeploySeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "crewDeployPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "approvalsSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "approvalsPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "checksSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "checksPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "releasePending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "runPlanSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "runPlanPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         Object.defineProperty(this, "hostsSeq", {
             enumerable: true,
             configurable: true,
@@ -281,6 +347,24 @@ export class SidecarHost {
             writable: true,
             value: []
         });
+        Object.defineProperty(this, "vapidKey", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "pushSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "pushPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         /** The synced directory name the daemon echoed for THIS connection
          * (`welcome.dirName`), or null against an older daemon that sends none. */
         Object.defineProperty(this, "dirName", {
@@ -289,6 +373,16 @@ export class SidecarHost {
             writable: true,
             value: null
         });
+        /** The daemon's verdict on the identity challenge/assert exchange, from
+         * `welcome.identity`, runtime-validated the same way `dirName`/`info` are:
+         * a malformed value is dropped to undefined (=> `identityVerified()`
+         * reports null, "not told"), never coerced. */
+        Object.defineProperty(this, "identity", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "info", {
             enumerable: true,
             configurable: true,
@@ -342,9 +436,29 @@ export class SidecarHost {
                 ...(this.opts.clientId ? { clientId: this.opts.clientId } : {}),
                 ...(this.opts.clientName ? { clientName: this.opts.clientName } : {}),
                 ...(this.opts.accounts?.length ? { accounts: this.opts.accounts } : {}),
+                ...(this.opts.wantsIdentity ? { wantsIdentity: true } : {}),
+                // What THIS client understands, so a daemon can tell an older app
+                // (whose agents sync but never fire until deployed) from this one.
+                capabilities: [CREW_DEPLOY_FEATURE],
             });
         });
     }
+    /** Answers the daemon's `identity-challenge`. `onIdentityChallenge` resolving
+     * a string sends it as the assertion; resolving `null`, having no handler
+     * at all, or THROWING all send `identity-assert` with no assertion -- every
+     * one of those is a considered "no identity to offer", never a reason to
+     * fail the handshake. The Clerk token itself never reaches this class: only
+     * whatever assertion the callback hands back does. */
+    async answerIdentityChallenge(m) {
+        let assertion = null;
+        try {
+            assertion = (await this.opts.onIdentityChallenge?.({ nonce: m.nonce, sidecarId: m.sidecarId })) ?? null;
+        }
+        catch {
+            assertion = null;
+        }
+        this.ch.send(assertion ? { t: 'identity-assert', assertion } : { t: 'identity-assert' });
+    }
     /** Drop the connection: unregister imported tools and fail anything in flight. */
     disconnect(reason = 'disconnected') {
         for (const name of this.imported)
@@ -359,6 +473,12 @@ export class SidecarHost {
         for (const p of this.runPending.values())
             p.reject(new Error(reason));
         this.runPending.clear();
+        // A cancel in flight when the connection drops did not get a considered
+        // answer -- resolve `unsupported` (not reject) so a Stop click during a
+        // drop does not hang the caller awaiting an ok/reason pair.
+        for (const p of this.cancelPending.values())
+            p({ ok: false, reason: 'unsupported' });
+        this.cancelPending.clear();
         for (const p of this.acpPending.values())
             p.reject(new Error(reason));
         this.acpPending.clear();
@@ -397,6 +517,21 @@ export class SidecarHost {
         for (const p of this.pausePending.values())
             p.reject(new Error(reason));
         this.pausePending.clear();
+        for (const p of this.crewDeployPending.values())
+            p.reject(new Error(reason));
+        this.crewDeployPending.clear();
+        for (const p of this.approvalsPending.values())
+            p.reject(new Error(reason));
+        this.approvalsPending.clear();
+        for (const p of this.checksPending.values())
+            p.reject(new Error(reason));
+        this.checksPending.clear();
+        for (const p of this.releasePending.values())
+            p.reject(new Error(reason));
+        this.releasePending.clear();
+        for (const p of this.runPlanPending.values())
+            p.reject(new Error(reason));
+        this.runPlanPending.clear();
         for (const p of this.hostsPending.values())
             p.reject(new Error(reason));
         this.hostsPending.clear();
@@ -434,6 +569,9 @@ export class SidecarHost {
         for (const p of this.mcpAdminPending.values())
             p.reject(new Error(reason));
         this.mcpAdminPending.clear();
+        for (const p of this.pushPending.values())
+            p.reject(new Error(reason));
+        this.pushPending.clear();
         /* The rejections above already drop each login's waiter via the wrapper
          * mcpLogin installs. Cleared here too so that stays true if sendMcpAdmin
          * is ever the one carrying a login -- a stale waiter would fire a consent
@@ -447,12 +585,19 @@ export class SidecarHost {
         switch (m.t) {
             case 'welcome': {
                 this.features = m.features ?? [];
+                // Runtime-validated: an untrusted/older daemon's `vapidPublicKey` is
+                // just a JSON-parsed `string`, and a malformed one must never be
+                // handed to the Push API. Anything that isn't the expected
+                // URL-safe-base64, 87-char shape is treated as "no key offered".
+                this.vapidKey = typeof m.vapidPublicKey === 'string' && /^[A-Za-z0-9_-]{87}$/.test(m.vapidPublicKey) ? m.vapidPublicKey : null;
                 // Runtime-validated like `info.id`/`info.name` next door: the welcome
                 // crossed the wire as `JSON.parse(...) as SidecarMsg`, so the declared
                 // `string` guarantees nothing, and this value decides which
                 // registrations a management surface treats as this browser's own.
                 // Anything malformed is dropped to "not told", never coerced.
                 this.dirName = typeof m.dirName === 'string' && m.dirName ? m.dirName : null;
+                this.identity = m.identity && typeof m.identity === 'object' && typeof m.identity.verified === 'boolean'
+                    ? m.identity : undefined;
                 this.info = m.info ?? {};
                 for (const decl of m.tools) {
                     const tool = { ...decl, run: (args) => this.invoke(decl.name, args) };
@@ -468,6 +613,10 @@ export class SidecarHost {
                 this.welcome = null;
                 return;
             }
+            case 'identity-challenge': {
+                void this.answerIdentityChallenge(m);
+                return;
+            }
             case 'invoke-result': {
                 const p = this.invokePending.get(m.id);
                 if (!p)
@@ -570,8 +719,10 @@ export class SidecarHost {
             }
             case 'run-accepted': {
                 const p = this.runPending.get(m.id);
-                if (p)
+                if (p) {
                     p.runId = m.runId;
+                    p.onAccepted?.(m.runId);
+                }
                 return;
             }
             case 'event': {
@@ -594,6 +745,12 @@ export class SidecarHost {
                 p.reject(new Error(m.error || 'run failed'));
                 return;
             }
+            case 'cancel-run-result': {
+                const p = this.cancelPending.get(m.id);
+                this.cancelPending.delete(m.id);
+                p?.(m.ok ? { ok: true } : { ok: false, ...(m.reason ? { reason: m.reason } : {}) });
+                return;
+            }
             case 'config-result': {
                 const p = this.configPending.get(m.id);
                 if (!p)
@@ -616,6 +773,17 @@ export class SidecarHost {
                     p.reject(new Error(m.error || 'host sync failed'));
                 return;
             }
+            case 'push-result': {
+                const p = this.pushPending.get(m.id);
+                if (!p)
+                    return;
+                this.pushPending.delete(m.id);
+                if (m.ok)
+                    p.resolve();
+                else
+                    p.reject(new Error(m.error));
+                return;
+            }
             case 'permission-ask': {
                 const { t: _t, ...ask } = m;
                 this.opts.onPermissionAsk?.(ask);
@@ -849,6 +1017,25 @@ export class SidecarHost {
                 this.opts.onRegistrations?.(m.registrations);
                 return;
             }
+            case 'approvals-suggest': {
+                const { t: _t, ...offer } = m;
+                this.opts.onApprovalSuggestion?.(offer);
+                return;
+            }
+            case 'approvals-accept-result':
+            case 'approvals-list-result':
+            case 'approvals-revoke-result': {
+                const p = this.approvalsPending.get(m.id);
+                if (!p)
+                    return;
+                this.approvalsPending.delete(m.id);
+                if (!m.ok) {
+                    p.resolve({ ok: false, error: m.error });
+                    return;
+                }
+                p.resolve(m.t === 'approvals-accept-result' ? { ok: true } : { ok: true, state: m.state });
+                return;
+            }
             case 'room-open-result': {
                 const p = this.roomOpenPending.get(m.id);
                 if (!p)
@@ -881,6 +1068,41 @@ export class SidecarHost {
                 p.resolve(m.ok ? { ok: true, pauses: m.pauses } : { ok: false, error: m.error });
                 return;
             }
+            case 'crew-deploy-result': {
+                // One pending map for all six crew-* requests: they share one reply shape.
+                const p = this.crewDeployPending.get(m.id);
+                if (!p)
+                    return;
+                this.crewDeployPending.delete(m.id);
+                p.resolve(m.reply);
+                return;
+            }
+            case 'checks-get-result':
+            case 'checks-pin-result': {
+                // One map for both: each answers with the complete state.
+                const p = this.checksPending.get(m.id);
+                if (!p)
+                    return;
+                this.checksPending.delete(m.id);
+                p.resolve(m.ok ? { ok: true, state: m.state } : { ok: false, error: m.error });
+                return;
+            }
+            case 'workspace-release-result': {
+                const p = this.releasePending.get(m.id);
+                if (!p)
+                    return;
+                this.releasePending.delete(m.id);
+                p.resolve(m.ok ? { ok: true, released: m.released } : { ok: false, error: m.error });
+                return;
+            }
+            case 'run-plan-get-result': {
+                const p = this.runPlanPending.get(m.id);
+                if (!p)
+                    return;
+                this.runPlanPending.delete(m.id);
+                p.resolve(m.ok ? { ok: true, plan: m.plan } : { ok: false, error: m.error });
+                return;
+            }
             case 'room-list-result': {
                 const p = this.roomListPending.get(m.id);
                 if (!p)
@@ -1211,6 +1433,12 @@ export class SidecarHost {
     /** The sidecar's advertised self-description (root/platform), or {} if it sent
      * none. Valid only after connect() resolves. */
     sidecarInfo() { return this.info; }
+    /** The daemon's verdict on the identity challenge/assert exchange for this
+     * connection. `null` means the daemon does not verify at all (no `identity`
+     * on `welcome` -- no verifier configured, or an older daemon), which is
+     * distinct from `false` (the exchange ran and was rejected, or the
+     * assertion never arrived). Valid only after connect() resolves. */
+    identityVerified() { return this.identity ? this.identity.verified : null; }
     /** 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. */
@@ -1251,7 +1479,7 @@ export class SidecarHost {
     run(agent, input, onEvent, opts) {
         const id = ++this.runSeq;
         return new Promise((resolve, reject) => {
-            this.runPending.set(id, { resolve, reject, onEvent });
+            this.runPending.set(id, { resolve, reject, onEvent, onAccepted: opts?.onAccepted });
             // `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.
@@ -1261,9 +1489,52 @@ export class SidecarHost {
                 t: 'run', id, agent, input,
                 ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
                 ...(opts?.keepTranscript ? { keepTranscript: true } : {}),
+                ...(opts?.task ? { task: opts.task } : {}),
+                ...(opts?.autonomy ? { autonomy: opts.autonomy } : {}),
             });
         });
     }
+    /** WATCH a run this client did not start (a trigger-fired crew run). Rides
+     * the same pending map as `run`, so `event`/`run-done`/`run-error` route here
+     * unchanged; the server replays what already happened first. */
+    watchRun(runId, onEvent) {
+        const id = ++this.runSeq;
+        let rejectDone;
+        const done = new Promise((resolve, reject) => {
+            rejectDone = reject;
+            this.runPending.set(id, {
+                resolve: (r) => resolve({ text: r.text, stopReason: r.stopReason }),
+                reject,
+                onEvent,
+            });
+            this.ch.send({ t: 'subscribe', id, runId });
+        });
+        return {
+            done,
+            // Client-side only: the server keeps the subscription until the run ends
+            // or the socket drops, and events for a closed id are ignored.
+            close: () => { if (this.runPending.delete(id))
+                rejectDone(new Error('closed')); },
+        };
+    }
+    /** Ask the daemon to cancel a running crew run. `ok: false, reason:
+     * 'no-such-run'` means the daemon has no such run (already finished, or
+     * never existed); `'unsupported'` means the daemon's runner has no `cancel`,
+     * or the connection dropped before the daemon answered. */
+    cancelRun(runId) {
+        const id = ++this.cancelSeq;
+        return new Promise((resolve) => {
+            this.cancelPending.set(id, resolve);
+            this.ch.send({ t: 'cancel-run', id, runId });
+        });
+    }
+    /** True when the connected sidecar's runner supports cancelling a run. */
+    supportsRunCancel() { return this.features.includes('run-cancel'); }
+    /** True when the connected sidecar understands `run`'s `task`/`autonomy`
+     * fields. An older sidecar without this feature would silently ignore
+     * them, so callers must check this before sending either — never send and
+     * hope. */
+    supportsTasks() { return this.features.includes(RUN_TASK_FEATURE); }
     /** 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
@@ -1313,9 +1584,10 @@ export class SidecarHost {
     }
     /** 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 });
+     * broadcast (`onPermissionResolved`), not by this call returning. `note` is
+     * the person's reason for a deny; the daemon trims and caps it. */
+    answerPermission(id, decision, note) {
+        this.ch.send({ t: 'permission-answer', id, decision, ...(note ? { note } : {}) });
     }
     /** Push one definition file's content to the daemon, to be persisted under
      * this client's own `<stateDir>/hosts/<dirName>/` (Slice 2 host sync).
@@ -1339,6 +1611,30 @@ export class SidecarHost {
             this.ch.send({ t: 'host-sync-delete', id, path });
         });
     }
+    /** The daemon's VAPID public key from `welcome`, or null when it offered
+     * none (older daemon, or an offered value that failed validation). */
+    vapidPublicKey() { return this.vapidKey; }
+    /** True when this daemon advertises web push AND handed over a usable key. */
+    supportsWebPush() { return this.features.includes('web-push') && this.vapidKey !== null; }
+    /** Send a browser push subscription to the daemon to persist. Resolves on
+     * `push-result { ok: true }`; rejects with the daemon's error, or on
+     * disconnect while in flight. */
+    pushSubscribe(subscription) {
+        const id = ++this.pushSeq;
+        return new Promise((resolve, reject) => {
+            this.pushPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'push-subscribe', id, subscription });
+        });
+    }
+    /** Tell the daemon to drop a subscription by endpoint. Same resolve/reject
+     * contract as `pushSubscribe`. */
+    pushUnsubscribe(endpoint) {
+        const id = ++this.pushSeq;
+        return new Promise((resolve, reject) => {
+            this.pushPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'push-unsubscribe', id, endpoint });
+        });
+    }
     /** True when this daemon serves its OWN Harness Config (`config-*`). Feature-
      * detected from the welcome, so a client standing on a daemon too old to serve
      * one says the config is unreachable instead of sending a message that will be
@@ -1504,6 +1800,105 @@ export class SidecarHost {
             this.ch.send({ t: 'agent-pause-set', id, owner, agent, paused });
         });
     }
+    /** True when the connected daemon keeps a deploy list (crew deploy per
+     * machine). Feature-detected from the welcome; without it a client shows
+     * the old read-only view. */
+    supportsCrewDeploy() { return this.features.includes(CREW_DEPLOY_FEATURE); }
+    /** One crew-* request. `ok: false` is the daemon's considered answer (a
+     * refusal names its rule) and resolves; only a dropped connection rejects.
+     * Against a daemon without the feature nothing is sent. */
+    crewDeployRequest(send) {
+        if (!this.supportsCrewDeploy())
+            return Promise.resolve({ ok: false, error: 'this daemon does not keep a deploy list' });
+        const id = ++this.crewDeploySeq;
+        return new Promise((resolve, reject) => {
+            this.crewDeployPending.set(id, { resolve, reject });
+            this.ch.send(send(id));
+        });
+    }
+    /** The machine's deploy list, statuses and audit. */
+    crewDeployments() { return this.crewDeployRequest((id) => ({ t: 'crew-deployments', id })); }
+    crewDeploy(ref, reason) { return this.crewDeployRequest((id) => ({ t: 'crew-deploy', id, ref, ...(reason ? { reason } : {}) })); }
+    crewUndeploy(ref, reason) { return this.crewDeployRequest((id) => ({ t: 'crew-undeploy', id, ref, ...(reason ? { reason } : {}) })); }
+    crewPause(ref, reason) { return this.crewDeployRequest((id) => ({ t: 'crew-pause', id, ref, reason })); }
+    crewResume(ref, reason) { return this.crewDeployRequest((id) => ({ t: 'crew-resume', id, ref, ...(reason ? { reason } : {}) })); }
+    /** Stop a run AND record who stopped it and why (the plain `cancelRun` records nothing). */
+    crewStop(ref, runId, reason) { return this.crewDeployRequest((id) => ({ t: 'crew-stop', id, ref, runId, reason })); }
+    /** True when the connected daemon keeps "This machine" standing approvals
+     * (plan 3). Feature-detected from the welcome. */
+    supportsApprovals() { return this.features.includes('approvals'); }
+    approvalsRequest(send) {
+        if (!this.supportsApprovals())
+            return Promise.resolve({ ok: false, error: 'this daemon does not keep standing approvals' });
+        const id = ++this.approvalsSeq;
+        return new Promise((resolve, reject) => {
+            this.approvalsPending.set(id, { resolve, reject });
+            this.ch.send(send(id));
+        });
+    }
+    /** Accept an offer this client received. The daemon checks that THIS
+     * connection is the one it offered to; `ok: false` is its refusal (expired,
+     * already used, offered to another connection), a real answer that
+     * resolves. Only a dropped connection rejects. */
+    async acceptApprovalSuggestion(suggestionId, choice) {
+        const r = await this.approvalsRequest((id) => ({ t: 'approvals-accept', id, suggestionId, choice }));
+        return r.ok ? { ok: true } : r;
+    }
+    /** The daemon's standing rules and its (daemon.json) approval settings. */
+    async listDaemonApprovals() {
+        return this.withState(await this.approvalsRequest((id) => ({ t: 'approvals-list', id })));
+    }
+    /** Remove one daemon standing rule; resolves with the complete state after. */
+    async revokeDaemonApproval(tool) {
+        return this.withState(await this.approvalsRequest((id) => ({ t: 'approvals-revoke', id, tool })));
+    }
+    withState(r) {
+        if (!r.ok)
+            return r;
+        return r.state ? { ok: true, state: r.state } : { ok: false, error: 'the daemon answered without its approvals state' };
+    }
+    /** True when the daemon runs confirmed checks and holds the orchestrator's
+     * workspace lock (it was started with --allow-shell, and its state dir is
+     * not inside an approved root). */
+    supportsChecks() { return this.features.includes('checks'); }
+    /** The folder's checks file, whether it is confirmed, and proposals. `ok:
+     * false` is the daemon's answer (no checks here, a bad path); only a dropped
+     * connection rejects. */
+    checksGet(root, stateDir) {
+        const id = ++this.checksSeq;
+        return new Promise((resolve, reject) => {
+            this.checksPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'checks-get', id, root, stateDir });
+        });
+    }
+    /** Write the content the user confirmed and pin its hash. */
+    checksPin(root, stateDir, content) {
+        const id = ++this.checksSeq;
+        return new Promise((resolve, reject) => {
+            this.checksPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'checks-pin', id, root, stateDir, content });
+        });
+    }
+    /** Hand back a run's workspace lock. `released: false` means this run did
+     * not hold it (already released, or held by another run). */
+    workspaceRelease(ref) {
+        const id = ++this.checksSeq;
+        return new Promise((resolve, reject) => {
+            this.releasePending.set(id, { resolve, reject });
+            this.ch.send({ t: 'workspace-release', id, root: ref.root, stateDir: ref.stateDir, runId: ref.runId });
+        });
+    }
+    /** True when the daemon answers run-plan-get. */
+    supportsRunPlan() { return this.features.includes(RUN_PLAN_FEATURE); }
+    /** One run's plan from its record. `ok: false` is the daemon's answer; only
+     * a dropped connection rejects. Ask only when supportsRunPlan() is true. */
+    runPlanGet(runId) {
+        const id = ++this.runPlanSeq;
+        return new Promise((resolve, reject) => {
+            this.runPlanPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'run-plan-get', id, runId });
+        });
+    }
     /** Ask the daemon to open a room. `ok: false` here is the daemon's CONSIDERED
      * refusal (validation problems, or an unreachable participant) — a real answer,
      * not a transport failure, so it resolves rather than rejects. Only a dropped