@corenel/harness 0.22.0 → 0.24.0

package/dist/sidecar/host.js

@@ -1,7 +1,10 @@
-import { CHAT_FEATURE, CHAT_ID_RE, FS_CHANGED_FEATURE } from '@corenel/protocol';
+import { CHAT_FEATURE, CHAT_ID_RE, FS_CHANGED_FEATURE, MCP_ALLOW_FEATURE } from '@corenel/protocol';
+import { KNOWLEDGE_FEATURE, KNOWLEDGE_NOT_KEPT } from '@corenel/protocol';
 import { asEcPublicJwk, jwkThumbprint, verifySignature, randomToken, serverProofPayload, clientProofPayload, parseEnrollmentCode, bytesToB64url, codeProof, codeHash, } from './deviceKeys.js';
 import { capabilityMissingMessage } from './hostCapability.js';
-import { SIDECAR_PROTOCOL, HOST_METHODS, errMessage, RUN_TASK_FEATURE, RUN_PLAN_FEATURE, CREW_DEPLOY_FEATURE, DEVICES_FEATURE, AGENT_ACCESS_FEATURE, AGENT_RUNS_FEATURE, PEER_LINKS_FEATURE, CHILD_EVENTS_FEATURE, PEER_DAEMON_FEATURE, TEAM_MEMBERS_FEATURE, SPEECH_FEATURE, encodePcm16, FLEET_LOGINS_DENIED, SIGN_IN_PAUSED_DENIED, isClerkOrgId, WORKFLOW_RUNNER_FEATURE, readWorkflowOkReply, readWorkflowResultsListReply, readWorkflowResultsTakeReply, } from '@corenel/protocol';
+import { SIDECAR_PROTOCOL, HOST_METHODS, errMessage, ATTENDANCE_LEAVE_FEATURE, ATTENDANCE_JOIN_FEATURE, RUN_TASK_FEATURE, RUN_PLAN_FEATURE, CREW_DEPLOY_FEATURE, FLEET_ITEMS_FEATURE, FLEET_USE_FEATURE, DEVICES_FEATURE, AGENT_ACCESS_FEATURE, AGENT_RUNS_FEATURE, PEER_LINKS_FEATURE, CHILD_EVENTS_FEATURE, PEER_DAEMON_FEATURE, TEAM_MEMBERS_FEATURE, SPEECH_FEATURE, SIDECAR_KNOWLEDGE_TOOLS, encodePcm16, FLEET_LOGINS_DENIED, SIGN_IN_PAUSED_DENIED, isClerkOrgId, WORKFLOW_RUNNER_FEATURE, readWorkflowOkReply, readWorkflowResultsListReply, readWorkflowResultsTakeReply, } from '@corenel/protocol';
+/** The sidecar knowledge tools a welcome may list, never registered as they are (see the welcome). */
+const SIDECAR_KNOWLEDGE_NAMES = new Set(SIDECAR_KNOWLEDGE_TOOLS);
 const NO_WORKFLOWS = 'this daemon does not run workflows';
 const WRONG_REPLY = 'the daemon answered with the wrong reply';
 /** A reply that failed its check (protocol workflowWire.ts readers). */
@@ -13,6 +16,11 @@ const MALFORMED_REPLY = 'the daemon sent a reply this app cannot read';
  * slow link. */
 export const WORKFLOW_REQUEST_TIMEOUT_MS = 60000;
 export const WORKFLOW_PUT_TIMEOUT_MS = 120000;
+/** After a fleet workflow call is stopped, how long the host waits for the sidecar's answer before it settles the
+ * call itself (a lost reply, a hung daemon, a cancel that did not land): Stop never hangs. Shorter than
+ * WORKFLOW_REQUEST_TIMEOUT_MS because a person is waiting on Stop. A late answer is dropped. */
+export const FLEET_CALL_STOP_GRACE_MS = 15000;
+export const FLEET_CALL_STOPPED = 'The fleet workflow call was stopped.';
 const NO_ANSWER = 'the sidecar did not answer in time';
 /** The longest root or path an `fs-changed` may name; a real one is far shorter. */
 const MAX_FS_CHANGE_LEN = 4096;
@@ -306,6 +314,55 @@ export class SidecarHost {
             writable: true,
             value: new Map()
         });
+        Object.defineProperty(this, "fleetItemsSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "knowledgeSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "knowledgePending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "fleetItemsPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /** One id sequence for the three fleet-use requests; each has its own reply map. */
+        Object.defineProperty(this, "fleetUseSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "fleetSkillCatalogPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "fleetWorkflowCatalogPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "fleetWorkflowCallPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         Object.defineProperty(this, "crewDeploySeq", {
             enumerable: true,
             configurable: true,
@@ -722,6 +779,14 @@ export class SidecarHost {
             writable: true,
             value: []
         });
+        /** The sidecar knowledge tools its welcome listed: never registered, called
+         * only through invokeKnowledgeTool. */
+        Object.defineProperty(this, "knowledgeTools", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
         Object.defineProperty(this, "welcome", {
             enumerable: true,
             configurable: true,
@@ -917,6 +982,9 @@ export class SidecarHost {
         for (const name of this.imported)
             this.opts.unregisterTool?.(name);
         this.imported.length = 0;
+        // A sidecar_knowledge_* tool listed by this connection's welcome is not
+        // listed by the next one until it says so again.
+        this.knowledgeTools.clear();
         for (const p of this.invokePending.values())
             p.reject(new Error(reason));
         this.invokePending.clear();
@@ -985,6 +1053,21 @@ export class SidecarHost {
         for (const p of this.crewDeployPending.values())
             p.reject(new Error(reason));
         this.crewDeployPending.clear();
+        for (const p of this.fleetItemsPending.values())
+            p.reject(new Error(reason));
+        this.fleetItemsPending.clear();
+        for (const p of this.knowledgePending.values())
+            p.reject(new Error(reason));
+        this.knowledgePending.clear();
+        for (const p of this.fleetSkillCatalogPending.values())
+            p.reject(new Error(reason));
+        this.fleetSkillCatalogPending.clear();
+        for (const p of this.fleetWorkflowCatalogPending.values())
+            p.reject(new Error(reason));
+        this.fleetWorkflowCatalogPending.clear();
+        for (const p of this.fleetWorkflowCallPending.values())
+            p.reject(new Error(reason));
+        this.fleetWorkflowCallPending.clear();
         for (const p of this.workflowsPending.values())
             p.reject(new Error(reason));
         this.workflowsPending.clear();
@@ -1115,7 +1198,20 @@ export class SidecarHost {
                     }
                     catch { /* the connection is up either way */ }
                 }
+                // Only what THIS welcome lists may be invoked: a later welcome on the
+                // same host (a reconnect) replaces the knowledge tools, never adds to them.
+                this.knowledgeTools.clear();
                 for (const decl of m.tools) {
+                    /* The sidecar's knowledge tools are never offered to a model as
+                     * they are: that would bypass the knowledge gating (the run's host,
+                     * its account, its grant) and the knowledge injection thresholds.
+                     * The browser offers them as knowledge_* (src/knowledge/hostKnowledge.ts)
+                     * and runs them on this machine through invokeKnowledgeTool, so the
+                     * output is checked under the knowledge_* name the model called. */
+                    if (SIDECAR_KNOWLEDGE_NAMES.has(decl.name)) {
+                        this.knowledgeTools.add(decl.name);
+                        continue;
+                    }
                     const tool = { ...decl, run: (args) => this.invoke(decl.name, args) };
                     this.opts.registerTool(tool);
                     this.imported.push(decl.name);
@@ -1562,7 +1658,11 @@ export class SidecarHost {
                 if (!p)
                     return;
                 this.mcpAdminPending.delete(m.id);
-                p.resolve({ ok: true });
+                p.resolve({
+                    ok: true,
+                    ...(typeof m.reloadError === 'string' ? { reloadError: m.reloadError } : {}),
+                    ...(Array.isArray(m.servers) ? { servers: m.servers } : {}),
+                });
                 return;
             }
             case 'mcp-admin-error': {
@@ -1575,7 +1675,11 @@ export class SidecarHost {
                 this.mcpAdminPending.delete(m.id);
                 // `reason` carried through so a caller can tell an ordinary refusal
                 // ("this server wants a pasted token") from a real failure.
-                p.resolve(m.reason ? { ok: false, error: m.error, reason: m.reason } : { ok: false, error: m.error });
+                p.resolve({
+                    ok: false, error: m.error,
+                    ...(m.reason ? { reason: m.reason } : {}),
+                    ...(m.code ? { code: m.code } : {}),
+                });
                 return;
             }
             /* A progress push, not a reply: the request stays pending. Delivered to
@@ -1702,6 +1806,51 @@ export class SidecarHost {
                 p.resolve(m.reply);
                 return;
             }
+            case 'knowledge-list-result':
+            case 'knowledge-set-result':
+            case 'knowledge-files-result':
+            case 'knowledge-file-result':
+            case 'knowledge-changes-result': {
+                const p = this.knowledgePending.get(m.id);
+                // A reply of another kind under this id answers nothing.
+                if (!p || p.t !== m.t)
+                    return;
+                this.knowledgePending.delete(m.id);
+                p.resolve(m);
+                return;
+            }
+            case 'fleet-items-result': {
+                const p = this.fleetItemsPending.get(m.id);
+                if (!p)
+                    return;
+                this.fleetItemsPending.delete(m.id);
+                p.resolve(m.reply);
+                return;
+            }
+            case 'fleet-skill-catalog-result': {
+                const p = this.fleetSkillCatalogPending.get(m.id);
+                if (!p)
+                    return;
+                this.fleetSkillCatalogPending.delete(m.id);
+                p.resolve(m.reply);
+                return;
+            }
+            case 'fleet-workflow-catalog-result': {
+                const p = this.fleetWorkflowCatalogPending.get(m.id);
+                if (!p)
+                    return;
+                this.fleetWorkflowCatalogPending.delete(m.id);
+                p.resolve(m.reply);
+                return;
+            }
+            case 'fleet-workflow-call-result': {
+                const p = this.fleetWorkflowCallPending.get(m.id);
+                if (!p)
+                    return;
+                this.fleetWorkflowCallPending.delete(m.id);
+                p.resolve(m.reply);
+                return;
+            }
             case 'workflow-package-result':
             case 'workflow-results-list-result':
             case 'workflow-results-take-result':
@@ -2421,6 +2570,39 @@ export class SidecarHost {
     answerPermission(id, decision, note) {
         this.ch.send({ t: 'permission-answer', id, decision, ...(note ? { note } : {}) });
     }
+    /** Stop attending on this connection while it stays open for this client's
+     * own calls: the daemon sends it no more permission asks, and an ask nobody
+     * else attends gets its unattended policy at once. Sent only to a daemon
+     * that advertises it (an older one would drop it unread); false when not. */
+    leaveAttendance() {
+        if (!this.features.includes(ATTENDANCE_LEAVE_FEATURE))
+            return false;
+        this.ch.send({ t: 'attendance-leave' });
+        return true;
+    }
+    /** Whether this daemon takes `attendance-join`, so a connection that left
+     * attendance can attend again without a new dial. */
+    canRejoinAttendance() {
+        return this.features.includes(ATTENDANCE_LEAVE_FEATURE) && this.features.includes(ATTENDANCE_JOIN_FEATURE);
+    }
+    /** True while an ACP session (its start entry lives as long as the session)
+     * or a dictation stream is open on this connection: its frames keep coming
+     * over this socket and its stop goes through it, so a client must not set
+     * the connection aside unseen while one is. */
+    hasLiveStreams() {
+        return this.acpPending.size > 0 || this.sttStreams.size > 0;
+    }
+    /** Attend again on this connection after `leaveAttendance`: the daemon
+     * replays the asks this connection may see, the registrations, the live
+     * runs and the recently settled task runs, through the usual handlers.
+     * Sent only to a daemon that advertises it; false when not, and the caller
+     * dials a new connection instead. */
+    joinAttendance() {
+        if (!this.canRejoinAttendance())
+            return false;
+        this.ch.send({ t: 'attendance-join' });
+        return true;
+    }
     /** 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
@@ -2584,8 +2766,8 @@ export class SidecarHost {
     /** The MCP servers configured on this machine, with credential PRESENCE.
      * There is no read path for a credential value anywhere in this feature. */
     mcpServers() { return this.sendMcpAdmin({ t: 'mcp-servers-list' }); }
-    /** Add a server to this machine's daemon.json. Takes effect on daemon
-     * restart -- the config plane cannot reach into a running daemon. */
+    /** Add a server to this machine's daemon.json. Resolves after the daemon
+     * applied it (`reloadError` when it could not yet). */
     mcpAddServer(name, url, hosted = false, authUrl) {
         /* Each field sent only when it has a value, so the message an older daemon
          * receives is byte-identical to what it received before these existed. */
@@ -2622,6 +2804,18 @@ export class SidecarHost {
     mcpSetCredential(name, header, value) {
         return this.sendMcpAdmin({ t: 'mcp-set-credential', name, header, value });
     }
+    /** Whether this daemon takes `mcpSetAllow`. */
+    supportsMcpAllow() { return this.features.includes(MCP_ALLOW_FEATURE); }
+    /** Switch which of server `name`'s tools this machine's `mcpAllow` grants:
+     * exactly `tools`, replacing that server's entries. Empty turns them all
+     * off. Resolves after the daemon applied it. Refused here, sending nothing,
+     * against a daemon without the feature: an older one would never answer. */
+    mcpSetAllow(name, tools) {
+        if (!this.supportsMcpAllow()) {
+            return Promise.resolve({ ok: false, error: 'this daemon cannot switch MCP tools -- update it and reconnect' });
+        }
+        return this.sendMcpAdmin({ t: 'mcp-allow-set', name, tools });
+    }
     sendMcpAdmin(body) {
         const id = ++this.mcpSeq;
         return new Promise((resolve, reject) => {
@@ -2687,6 +2881,134 @@ export class SidecarHost {
             this.ch.send(send(id));
         });
     }
+    /** True when the connected sidecar keeps its own knowledge folders and
+     * answers the knowledge-* messages. */
+    supportsKnowledge() { return this.features.includes(KNOWLEDGE_FEATURE); }
+    /** Send one knowledge request and resolve with the reply of kind `t` under
+     * its id. Against a sidecar without the feature nothing is sent. `ok: false`
+     * is the sidecar's considered answer and resolves; only a dropped connection
+     * rejects. */
+    knowledgeCall(t, request, replyOf, unsupported) {
+        if (!this.supportsKnowledge())
+            return Promise.resolve(unsupported);
+        const id = ++this.knowledgeSeq;
+        return new Promise((resolve, reject) => {
+            this.knowledgePending.set(id, {
+                t,
+                resolve: (m) => {
+                    const reply = replyOf(m);
+                    if (reply === undefined)
+                        reject(new Error(`unexpected ${m.t}`));
+                    else
+                        resolve(reply);
+                },
+                reject,
+            });
+            this.ch.send(request(id));
+        });
+    }
+    /** Run one of the sidecar's knowledge tools (sidecar_knowledge_*), which the
+     * welcome listed and nothing registered. Any other name, or one the welcome
+     * did not list, is refused without sending. */
+    invokeKnowledgeTool(name, args) {
+        if (!SIDECAR_KNOWLEDGE_NAMES.has(name) || !this.knowledgeTools.has(name)) {
+            return Promise.reject(new Error(`sidecar tool not connected: ${name}`));
+        }
+        return this.invoke(name, args);
+    }
+    /** The connected sidecar's knowledge folders, and whether this connection manages them. */
+    knowledgeList() {
+        return this.knowledgeCall('knowledge-list-result', (id) => ({ t: 'knowledge-list', id }), (m) => (m.t === 'knowledge-list-result' ? m.reply : undefined), { ok: false, error: KNOWLEDGE_NOT_KEPT });
+    }
+    /** Add one folder or remove one by id; answers the new list. Refused by the
+     * sidecar unless this connection manages its folders. */
+    knowledgeSet(change) {
+        return this.knowledgeCall('knowledge-set-result', (id) => ({ t: 'knowledge-set', id, ...change }), (m) => (m.t === 'knowledge-set-result' ? m.reply : undefined), { ok: false, error: KNOWLEDGE_NOT_KEPT });
+    }
+    /** The files in one knowledge folder, by its id. */
+    knowledgeFiles(folder) {
+        return this.knowledgeCall('knowledge-files-result', (id) => ({ t: 'knowledge-files', id, folder }), (m) => (m.t === 'knowledge-files-result' ? m.reply : undefined), { ok: false, error: KNOWLEDGE_NOT_KEPT });
+    }
+    /** One file's text, or with `stat` its size and mtime, in one knowledge folder. */
+    knowledgeFile(folder, path, stat = false) {
+        return this.knowledgeCall('knowledge-file-result', (id) => ({ t: 'knowledge-file', id, folder, path, ...(stat ? { stat: true } : {}) }), (m) => (m.t === 'knowledge-file-result' ? m.reply : undefined), { ok: false, error: KNOWLEDGE_NOT_KEPT });
+    }
+    /** What was written into the sidecar's knowledge folders, newest first. */
+    knowledgeChanges() {
+        return this.knowledgeCall('knowledge-changes-result', (id) => ({ t: 'knowledge-changes', id }), (m) => (m.t === 'knowledge-changes-result' ? m.reply : undefined), { ok: false, error: KNOWLEDGE_NOT_KEPT });
+    }
+    /** True when the connected sidecar lists its fleet items. */
+    supportsFleetItems() { return this.features.includes(FLEET_ITEMS_FEATURE); }
+    /** The fleet agents, skills and workflows installed on the connected
+     * sidecar. `ok: false` is its considered answer and resolves; only a dropped
+     * connection rejects. Against a sidecar without the feature nothing is sent. */
+    fleetItems() {
+        if (!this.supportsFleetItems())
+            return Promise.resolve({ ok: false, error: 'this sidecar does not list fleet items' });
+        const id = ++this.fleetItemsSeq;
+        return new Promise((resolve, reject) => {
+            this.fleetItemsPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'fleet-items', id });
+        });
+    }
+    /** True when the connected sidecar offers its fleet skills and workflows for use. */
+    supportsFleetUse() { return this.features.includes(FLEET_USE_FEATURE); }
+    /** The fleet skills the connected sidecar offers now. `ok: false` is its considered answer and resolves; only
+     * a dropped connection rejects. Against a sidecar without the feature nothing is sent. */
+    fleetSkillCatalog() {
+        if (!this.supportsFleetUse())
+            return Promise.resolve({ ok: false, error: 'this sidecar does not offer fleet items' });
+        const id = ++this.fleetUseSeq;
+        return new Promise((resolve, reject) => {
+            this.fleetSkillCatalogPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'fleet-skill-catalog', id });
+        });
+    }
+    /** The fleet workflows the connected sidecar can run now. Same contract as fleetSkillCatalog. */
+    fleetWorkflowCatalog() {
+        if (!this.supportsFleetUse())
+            return Promise.resolve({ ok: false, error: 'this sidecar does not offer fleet items' });
+        const id = ++this.fleetUseSeq;
+        return new Promise((resolve, reject) => {
+            this.fleetWorkflowCatalogPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'fleet-workflow-catalog', id });
+        });
+    }
+    /** Run one fleet workflow on the connected sidecar and wait for its final text. Aborting `signal` sends
+     * `fleet-workflow-cancel` and waits up to FLEET_CALL_STOP_GRACE_MS for the sidecar's answer (the run settles as
+     * stopped); with none by then the call is forgotten (a late answer is dropped) and resolves FLEET_CALL_STOPPED.
+     * An already-aborted signal sends nothing. `ok: false` resolves; only a dropped connection rejects. */
+    callFleetWorkflow(name, inputs, signal) {
+        if (!this.supportsFleetUse())
+            return Promise.resolve({ ok: false, error: 'this sidecar does not offer fleet items' });
+        if (signal.aborted)
+            return Promise.resolve({ ok: false, error: FLEET_CALL_STOPPED });
+        const id = ++this.fleetUseSeq;
+        return new Promise((resolve, reject) => {
+            let timer;
+            const onAbort = () => {
+                if (!this.fleetWorkflowCallPending.has(id))
+                    return;
+                this.ch.send({ t: 'fleet-workflow-cancel', id });
+                timer = setTimeout(() => {
+                    if (!this.fleetWorkflowCallPending.delete(id))
+                        return;
+                    resolve({ ok: false, error: FLEET_CALL_STOPPED });
+                }, FLEET_CALL_STOP_GRACE_MS);
+            };
+            const settle = () => {
+                signal.removeEventListener('abort', onAbort);
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            };
+            this.fleetWorkflowCallPending.set(id, {
+                resolve: (r) => { settle(); resolve(r); },
+                reject: (e) => { settle(); reject(e); },
+            });
+            signal.addEventListener('abort', onAbort, { once: true });
+            this.ch.send({ t: 'fleet-workflow-call', id, name, inputs });
+        });
+    }
     /** The machine's deploy list, statuses and audit. */
     crewDeployments() { return this.crewDeployRequest((id) => ({ t: 'crew-deployments', id })); }
     /** Deploy an agent or a workflow. `workspaceId`: where a deployed