@khorsheed/dsh-local-agent 0.2.0-rc.1 → 0.2.0

package/lib/types/gateway.js

@@ -82,6 +82,11 @@ let LocalAgentGateway = (() => {
     let _sessions_decorators;
     let _memberOf_decorators;
     let _harnessModel_decorators;
+    let _checkEndpoint_decorators;
+    let _endpointAuth_decorators;
+    let _configureEndpoint_decorators;
+    let _modelList_decorators;
+    let _configureModelList_decorators;
     let _memberModel_decorators;
     let _setMemberModel_decorators;
     let _memberConfiguration_decorators;
@@ -108,6 +113,11 @@ let LocalAgentGateway = (() => {
             _sessions_decorators = [Remote('sessions')];
             _memberOf_decorators = [Remote('memberOf')];
             _harnessModel_decorators = [Remote('harnessModel')];
+            _checkEndpoint_decorators = [Remote('checkEndpoint')];
+            _endpointAuth_decorators = [Remote('endpointAuth')];
+            _configureEndpoint_decorators = [Remote('configureEndpoint')];
+            _modelList_decorators = [Remote('modelList')];
+            _configureModelList_decorators = [Remote('configureModelList')];
             _memberModel_decorators = [Remote('memberModel')];
             _setMemberModel_decorators = [Remote('setMemberModel')];
             _memberConfiguration_decorators = [Remote('memberConfiguration')];
@@ -131,6 +141,11 @@ let LocalAgentGateway = (() => {
             __esDecorate(this, null, _sessions_decorators, { kind: "method", name: "sessions", static: false, private: false, access: { has: obj => "sessions" in obj, get: obj => obj.sessions }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _memberOf_decorators, { kind: "method", name: "memberOf", static: false, private: false, access: { has: obj => "memberOf" in obj, get: obj => obj.memberOf }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _harnessModel_decorators, { kind: "method", name: "harnessModel", static: false, private: false, access: { has: obj => "harnessModel" in obj, get: obj => obj.harnessModel }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _checkEndpoint_decorators, { kind: "method", name: "checkEndpoint", static: false, private: false, access: { has: obj => "checkEndpoint" in obj, get: obj => obj.checkEndpoint }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _endpointAuth_decorators, { kind: "method", name: "endpointAuth", static: false, private: false, access: { has: obj => "endpointAuth" in obj, get: obj => obj.endpointAuth }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _configureEndpoint_decorators, { kind: "method", name: "configureEndpoint", static: false, private: false, access: { has: obj => "configureEndpoint" in obj, get: obj => obj.configureEndpoint }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _modelList_decorators, { kind: "method", name: "modelList", static: false, private: false, access: { has: obj => "modelList" in obj, get: obj => obj.modelList }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _configureModelList_decorators, { kind: "method", name: "configureModelList", static: false, private: false, access: { has: obj => "configureModelList" in obj, get: obj => obj.configureModelList }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _memberModel_decorators, { kind: "method", name: "memberModel", static: false, private: false, access: { has: obj => "memberModel" in obj, get: obj => obj.memberModel }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _setMemberModel_decorators, { kind: "method", name: "setMemberModel", static: false, private: false, access: { has: obj => "setMemberModel" in obj, get: obj => obj.setMemberModel }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _memberConfiguration_decorators, { kind: "method", name: "memberConfiguration", static: false, private: false, access: { has: obj => "memberConfiguration" in obj, get: obj => obj.memberConfiguration }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -330,6 +345,80 @@ let LocalAgentGateway = (() => {
                 ? info
                 : { ...info, lastObserved: observed });
         }
+        /**
+         * Verify one harness's saved endpoint from the host — the settings card's
+         * verify button. The answer is the harness's human-readable verdict text.
+         * Session-less by design: the commands channel needs a main agent session,
+         * which a settings card may not have. Null when the harness is unknown or
+         * declares no probe (the card then hides the button — declare-and-degrade).
+         * @param name - the harness name.
+         * @returns the verdict text, or null.
+         */
+        async checkEndpoint(name) {
+            const harness = this.ctx.localAgent.get(name);
+            if (typeof harness?.checkEndpoint !== 'function')
+                return null;
+            return harness.checkEndpoint(this.ctx.localAgent.homeDir(name));
+        }
+        /**
+         * The settings card's read of one harness's resolved endpoint state —
+         * baseUrl verbatim, credentials as presence booleans (secrets never cross).
+         * Session-less like the rest of the gateway. Null when the harness is
+         * unknown or declares no endpoint face (the card then hides the form).
+         * @param name - the harness name.
+         * @returns the resolved per-field state, or null.
+         */
+        async endpointAuth(name) {
+            const harness = this.ctx.localAgent.get(name);
+            if (harness?.endpointAuth === undefined)
+                return null;
+            return harness.endpointAuth.read(this.ctx.localAgent.homeDir(name));
+        }
+        /**
+         * Apply one endpoint-credential edit into the harness's own credential
+         * store (a string sets, null clears, absent leaves), answering the
+         * post-write resolved state so the card can flip immediately. The write
+         * deliberately bypasses the volatile row-config channel — a credential
+         * never lands in the profile patch document. Null when the harness is
+         * unknown or declares no endpoint face.
+         * @param name - the harness name.
+         * @param fields - the field edits.
+         * @returns the post-write resolved state, or null.
+         */
+        async configureEndpoint(name, fields) {
+            const harness = this.ctx.localAgent.get(name);
+            if (harness?.endpointAuth === undefined)
+                return null;
+            await harness.endpointAuth.write(this.ctx.localAgent.homeDir(name), fields);
+            return harness.endpointAuth.read(this.ctx.localAgent.homeDir(name));
+        }
+        /**
+         * The settings card's read of one harness's curated model list — ordered
+         * identifiers, first is the default. Null when the harness is unknown or
+         * declares no list face (the card then hides the editor).
+         * @param name - the harness name.
+         * @returns the ordered list, or null.
+         */
+        async modelList(name) {
+            const harness = this.ctx.localAgent.get(name);
+            if (harness?.modelList === undefined)
+                return null;
+            return harness.modelList.read(this.ctx.localAgent.homeDir(name));
+        }
+        /**
+         * Replace one harness's curated model list wholesale (reorders, removals
+         * and additions all ride the same write), answering the list as persisted.
+         * Null when the harness is unknown or declares no list face.
+         * @param name - the harness name.
+         * @param models - the new ordered list.
+         * @returns the persisted list, or null.
+         */
+        async configureModelList(name, models) {
+            const harness = this.ctx.localAgent.get(name);
+            if (harness?.modelList === undefined)
+                return null;
+            return harness.modelList.write(this.ctx.localAgent.homeDir(name), models);
+        }
         /**
          * The model surface of one member — the composer's picker read. The
          * delegation record's requested model rides in from the core so the broker

package/lib/types/index.d.ts

@@ -22,7 +22,7 @@ import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands
 import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm';
 import type { Session, SessionHeader } from '@deepseek-ai/dsh-session';
 import type { SubagentRun } from '@deepseek-ai/dsh-subagent';
-import type { DelegationCallOptions, LocalAgentDelegationInfo, LocalAgentDelegationIntent, LocalAgentDelegationRecord, LocalAgentEffectiveSettings, LocalAgentMemberRun, LocalAgentModelBroker, LocalAgentMemberBinding, LocalAgentMemberControlState, LocalAgentMemberInbox, LocalAgentMemberConfiguration, LocalAgentControlReceipt, LocalAgentAppliedConfiguration, LocalAgentRosterRow, LocalAgentRunProgress, LocalAgentSessionRecord, LocalAgentStatus, LocalAgentToolCalls } from './types.ts';
+import type { DelegationCallOptions, LocalAgentDelegationInfo, LocalAgentDelegationIntent, LocalAgentDelegationRecord, LocalAgentEffectiveSettings, LocalAgentEndpointAuthFields, LocalAgentEndpointAuthState, LocalAgentMemberRun, LocalAgentModelBroker, LocalAgentMemberBinding, LocalAgentMemberControlState, LocalAgentMemberInbox, LocalAgentMemberConfiguration, LocalAgentControlReceipt, LocalAgentAppliedConfiguration, LocalAgentRosterRow, LocalAgentRunProgress, LocalAgentSessionRecord, LocalAgentStatus, LocalAgentToolCalls } from './types.ts';
 import { MemberInbox } from './member-inbox.ts';
 /** Stable Cordis plugin name. */
 export declare const name = "local-agent";
@@ -33,6 +33,7 @@ export type { DelegationCallOptions, LocalAgentCredentialState, DelegationExecTa
 export type { LocalAgentMemberMessage, MemberMessageOutcome, RoomMemberMessageGate, RoomMemberMessageReceipt, } from './types.ts';
 export { delegationEnv } from './env.ts';
 export { ModelDirectoryCache, extendModelDirectory, modelDirectoryContextKey } from './model-directory.ts';
+export { MODEL_LIST_FILE, firstModelOf, normalizeModelList, readModelList, readModelListSync, writeModelList } from './model-list.ts';
 export { MemberConfigurationController } from './member-control.ts';
 export type { MemberConfigurationAdapter, MemberControlStorage, MemberControlRecord } from './member-control.ts';
 export { FileMemberControlStorage } from './member-control-storage.ts';
@@ -229,9 +230,7 @@ export interface LocalAgentHarness {
     homeEnvVar: string;
     /**
      * Subagent provider name this harness delegates through, when it has one.
-     * A harness without delegation is record-and-login only. The core invariant
-     * cross-checks this against the mounted subagent providers, so a record
-     * that names a provider the composition does not mount fails loud.
+     * A harness without delegation is record-and-login only.
      */
     delegationProvider?: string;
     /**
@@ -275,6 +274,39 @@ export interface LocalAgentHarness {
      */
     isAuthenticated?: (homeDir: string) => Promise<boolean>;
     /**
+     * Optional host-side endpoint verification (the settings card's verify
+     * button): a cheap, token-free probe of the SAVED endpoint configuration,
+     * answered as human-readable verdict text. It rides the session-less
+     * gateway Remote (`checkEndpoint`) because a settings card may have no
+     * main agent session to run a slash command through. Absent means the
+     * harness has no such probe and the card must not offer the button.
+     */
+    checkEndpoint?: (homeDir: string) => Promise<string>;
+    /**
+     * Optional endpoint-credential face for the settings card: a read of the
+     * resolved per-field state (secrets as booleans, never echoed) and a write
+     * that applies edits into the harness's OWN credential store. The card
+     * talks to it through the session-less gateway Remotes
+     * (`endpointAuth`/`configureEndpoint`) instead of the volatile row-config
+     * channel — a credential never belongs in the profile patch document, and
+     * that channel rejects writes a deployment cannot explain. Absent means
+     * the card renders no endpoint form.
+     */
+    endpointAuth?: {
+        read(homeDir: string): Promise<LocalAgentEndpointAuthState>;
+        write(homeDir: string, fields: LocalAgentEndpointAuthFields): Promise<void>;
+    };
+    /**
+     * Optional curated model-list face: an ORDERED list of model identifiers
+     * the harness persists in its own store (its first entry is the harness's
+     * default model). The settings card edits it through the session-less
+     * `modelList`/`configureModelList` gateway Remotes. Absent means the card
+     * renders no model-list editor.
+     */
+    modelList?: {
+        read(homeDir: string): Promise<readonly string[]>;
+        write(homeDir: string, models: readonly string[]): Promise<readonly string[]>;
+    }; /**
      * The credential marker's modification stamp (epoch ms), undefined when no
      * credential exists. Two consumers: the manual-login watch requires a stamp
      * NEWER than the watch start (a stale marker must not read as a fresh
@@ -616,9 +648,9 @@ export declare class LocalAgentRegistry {
     /**
      * Per-(parent session, provider) FIFO of delegation intents. The family
      * resume tool stages exactly one intent per call before awaiting
-     * `ctx.subagents.start()`, and the owning provider consumes exactly one per
-     * start, so fresh and resume rounds stay paired even under parallel
-     * delegations from one parent.
+     * `ctx.subagents.startActivation()`, and the owning provider consumes
+     * exactly one per start, so fresh and resume rounds stay paired even under
+     * parallel delegations from one parent.
      */
     private readonly delegationIntents;
     /**
@@ -671,10 +703,12 @@ export declare class LocalAgentRegistry {
      * - **facade-tracked** ({@link trackRun}): runs started through
      *   {@link LocalAgentRegistry.start} / {@link LocalAgentRegistry.resume},
      *   carrying the fused AbortController whose signal reached
-     *   `ctx.subagents.start`; cancel aborts it.
+     *   `ctx.subagents.startActivation`; cancel aborts the pre-publication
+     *   signal and disposes the published activation.
      * - **tool-registered** ({@link trackDelegationRun}): runs the family tool
-     *   starts directly through `ctx.subagents.start`, carrying an explicit
-     *   cancel lever (its fused controller); cancel calls it.
+     *   starts directly through `ctx.subagents.startActivation`, carrying an
+     *   explicit cancel lever (its fused controller plus the activation's
+     *   dispose); cancel calls it.
      *
      * Every entry clears itself when the run's result settles (any stop
      * reason), and facade entries also stop their heartbeat timer then.
@@ -917,9 +951,10 @@ export declare class LocalAgentRegistry {
     /**
      * Stage one delegation intent for a provider's next `start()`. The family
      * resume tool stages exactly one intent per call before awaiting
-     * `ctx.subagents.start()`; the provider consumes exactly one per start via
-     * {@link takeDelegationIntent}, so the per-(parent, provider) FIFO pairs
-     * fresh and resume rounds even under parallel delegations from one parent.
+     * `ctx.subagents.startActivation()`; the provider consumes exactly one per
+     * start via {@link takeDelegationIntent}, so the per-(parent, provider)
+     * FIFO pairs fresh and resume rounds even under parallel delegations from
+     * one parent.
      * @param parentSessionId - the delegating parent session id.
      * @param provider - the `ctx.subagents` provider name.
      * @param intent - the fresh or resume intent for the next start.
@@ -936,7 +971,7 @@ export declare class LocalAgentRegistry {
     takeDelegationIntent(parentSessionId: string, provider: string): LocalAgentDelegationIntent | undefined;
     /**
      * Remove one previously staged intent by reference, returning whether it was
-     * still queued. The delegation facade calls this when `ctx.subagents.start()`
+     * still queued. The delegation facade calls this when `ctx.subagents.startActivation()`
      * throws: an intent the provider never consumed must not linger in the FIFO,
      * where the NEXT same-(parent, provider) start would misconsume it as its own
      * (orphan-intent crosstalk). When the provider already consumed the intent
@@ -950,9 +985,7 @@ export declare class LocalAgentRegistry {
      */
     unstageDelegationIntent(parentSessionId: string, provider: string, intent: LocalAgentDelegationIntent): boolean;
     /**
-     * Every recorded delegation, in recording order. The invariant companion
-     * cross-checks each record's provider against the mounted subagent
-     * providers so a provider rename cannot leave a stale resume mapping.
+     * Every recorded delegation, in recording order.
      * @returns the recorded delegations.
      */
     listDelegations(): readonly LocalAgentDelegationRecord[];
@@ -1107,7 +1140,9 @@ export declare class LocalAgentRegistry {
      * {@link unstageDelegationIntent} (a no-op once the provider consumed it).
      *
      * The returned run is tracked under its `run.id` (== the new dsh child
-     * session id) until `run.result` settles; {@link cancel} aborts it by that
+     * session id, minted here and carried to the provider through the staged
+     * intent — host 0.2.1's `startActivation` never surfaces it on the
+     * activation) until `run.result` settles; {@link cancel} aborts it by that
      * id. Note on trust: cordis plugins share one process, so the ownership
      * checks here and in {@link resume} guard against caller MISTAKES, not
      * against a malicious plugin — their real protection target is untrusted
@@ -1137,12 +1172,12 @@ export declare class LocalAgentRegistry {
      *    without staging; the provider still takes the authoritative lock inside
      *    its `start()`;
      * 4. live parent agent resolution (`ctx.agents.get`) — a harness hard
-     *    constraint, since `ctx.subagents.start` requires a live parent;
+     *    constraint, since `ctx.subagents.startActivation` requires a live parent;
      * 5. child-session REATTACH when `ctx.sessions.get(childSessionId)` is
      *    undefined (recipe below; `opts.reattach === false` disables this step
      *    and fails loud on a non-live child instead);
      * 6. stage `{ kind: 'resume', childSessionId, cliSessionId }` and, in the
-     *    same synchronous flow, `await ctx.subagents.start(provider, …)`;
+     *    same synchronous flow, `await ctx.subagents.startActivation({…})`;
      * 7. on start failure, roll the intent back via
      *    {@link unstageDelegationIntent} (no-op once consumed);
      * 8. on success, track the run under `childSessionId` for {@link cancel}
@@ -1155,8 +1190,12 @@ export declare class LocalAgentRegistry {
      * const handle = await ctx.sessionPersistence.open(SessionId(childSessionId), 'write')
      * try {
      *   const cold = await handle.read(0)
+     *   // Close a turn a restart interrupted, or the next round's turn/start
+     *   // makes the stored log unreadable.
+     *   const closers = interruptedTurnClosers(cold.events)
+     *   if (closers.length > 0) await handle.append(closers)
      *   const session = ctx.sessions.prepare(SessionId(childSessionId), {
-     *     seed: [...cold.events],
+     *     seed: [...cold.events, ...closers],
      *     meta: structuredClone(handle.header),
      *     inheritedEventCount: handle.inheritedEventCount,
      *     eventState: cold.eventState,
@@ -1164,7 +1203,7 @@ export declare class LocalAgentRegistry {
      *   // The seeded constructor's session/end-seed marker lands before enter()
      *   // installs publication hooks — push the unstored suffix through the
      *   // handle directly, or the writer's contiguous cursor diverges.
-     *   const unstored = session.snapshotEvents().slice(cold.events.length)
+     *   const unstored = session.snapshotEvents().slice(cold.events.length + closers.length)
      *   if (unstored.length > 0) await handle.append(unstored)
      *   const detach = ctx.sessions.enter(session)
      *   try { ctx.sessions.announce(session) }
@@ -1196,11 +1235,12 @@ export declare class LocalAgentRegistry {
      */
     resume(parentSessionId: string, provider: string, childSessionId: string, prompt: ContentBlock[], options?: DelegationCallOptions): Promise<SubagentRun>;
     /**
-     * Cancel an in-flight facade-started run by its dsh child session id: aborts
-     * the internal controller whose (fused) signal was passed to
-     * `ctx.subagents.start`, which is the canonical cancellation channel for a
-     * one-shot run. The provider settles the run with an `aborted`-class stop
-     * reason. A caller holding the `SubagentRun` may also `run.dispose()`.
+     * Cancel an in-flight facade-started run by its dsh child session id:
+     * aborts the internal controller (the pre-publication channel fused into
+     * the activation's start signal) and disposes the activation — host 0.2.1's
+     * canonical POST-publication cancellation, which settles the run with an
+     * `aborted`-class stop reason. A caller holding the `SubagentRun` may also
+     * `run.dispose()`.
      * @param childSessionId - the dsh child session id of the run to cancel.
      * @returns whether an in-flight run was found and signalled (false on a
      *   miss — never a silent success, never a throw).
@@ -1210,16 +1250,17 @@ export declare class LocalAgentRegistry {
      * Register a NON-facade in-flight delegation run with the active-delegation
      * registry, keyed by the dsh child session id, so the `/local-agent stop`
      * command and {@link cancel} can reach it. This is the family TOOL's entry
-     * point: the tool starts its runs through `ctx.subagents.start` directly
-     * (not the facade), so without this registration its in-flight runs would
-     * be invisible to the stop command. The caller owns the cancel lever — a
-     * controller fused with the run's request signal, aborted exactly like the
-     * facade's tracked controller. The entry clears itself when the run's
-     * result settles (any stop reason); an existing facade entry for the same
-     * child session wins (it already owns cancellation and progress).
-     * @param childSessionId - the dsh child session id (the run id).
-     * @param run - the published subagent run.
-     * @param cancel - the lever that aborts the run's request signal.
+     * point: the tool starts its runs through `ctx.subagents.startActivation`
+     * directly (not the facade), so without this registration its in-flight
+     * runs would be invisible to the stop command. The caller owns the cancel
+     * lever — aborting the fused controller (pre-publication) and disposing the
+     * activation (post-publication), the same channels the facade drives. The
+     * entry clears itself when the run's result settles (any stop reason); an
+     * existing facade entry for the same child session wins (it already owns
+     * cancellation and progress).
+     * @param childSessionId - the dsh child session id.
+     * @param run - the published subagent run (the tool's activation adapter).
+     * @param cancel - the lever that cancels the run.
      */
     trackDelegationRun(childSessionId: string, run: SubagentRun, cancel: () => void): void;
     /**
@@ -1267,7 +1308,7 @@ export declare class LocalAgentRegistry {
      * from persistence when it is not — a host restart evicts every child from
      * the live store. This is the public entry of the facade resume's reattach
      * recipe for callers that start resume rounds WITHOUT the facade (the
-     * family subagent tool starts runs directly through `ctx.subagents.start`;
+     * family subagent tool starts runs directly through `ctx.subagents.startActivation`;
      * without this call the provider refuses the resume as "not live").
      * Idempotent; a child that was never persisted fails through the
      * persistence layer's own not-found error.
@@ -1299,6 +1340,18 @@ export declare class LocalAgentRegistry {
      * @param session - the live child session to sync.
      */
     syncChildSession(session: Session, strict?: boolean): Promise<void>;
+    /**
+     * One sync pass. While the write handle is open the host routes every live
+     * append into the writer's buffer, so the routed events are drained first
+     * (`sessions.flush`: drain + flush) and only what is STILL missing — events
+     * from before the handle opened, or a host that routes nothing — goes in
+     * explicitly, bounded to the events that existed before the drain. Appending
+     * routed-but-undrained events explicitly as well would land them twice: the
+     * explicit write wins, the buffered copy then fails contiguity forever, and
+     * every later flush — the host's tool-execution checkpoint included —
+     * throws "append seq mismatch".
+     */
+    private syncChildSessionOnce;
     /**
      * Get or open the child session's registry-owned WRITE handle (the
      * {@link childWriteHandles} cache). When the caller carries the session