@achasoft/dsh-advanced-sidebar 0.1.0

package/types/host/tasks.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Background-task control for the Tasks panel.
+ *
+ * The list itself is not here: the Host already pushes `session/jobs` frames that the Web Client
+ * folds into its `jobsBySession` mirror, so the panel reads the same live data every other surface
+ * reads and this module owns only the two verbs that mirror has no wire for — stop, and output.
+ *
+ * Output is the delicate one. `ctx.jobs.read()` CONSUMES a stream job's delta, and the model reads
+ * the same cursor through its own jobs tool; draining it for a person would silently delete output
+ * the model was about to receive. So output is served only once the registry has marked the record
+ * reported — after a kill, a wait, or a model read — and the text is accumulated here so reopening
+ * the panel shows the same output instead of an empty second read.
+ * @module @achasoft/dsh-advanced-sidebar/host/tasks
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AdvancedSidebarSettings, CapabilityState, TaskKillRequest, TaskKillResult, TaskOutputRequest, TaskOutputResult } from './types.ts';
+/**
+ * Stops and reads background tasks on behalf of the Tasks panel. One instance serves every request
+ * and retains the output it has already drained.
+ */
+export declare class TaskController {
+    private readonly ctx;
+    private readonly source;
+    /** Accumulated output per job id, so a second panel open is not an empty read. */
+    private readonly collected;
+    /**
+     * Tasks whose output has already been taken.
+     *
+     * `read()` is CONSUMING for a stream job and IDEMPOTENT for a final-output one, and the snapshot
+     * does not say which kind a job is. Appending every read would therefore duplicate a
+     * final-output job's text once per poll, so each task is drained exactly once — after settlement,
+     * when there is nothing further to come.
+     */
+    private readonly drained;
+    /**
+     * @param ctx - Host context carrying the optional job registry and the agent registry.
+     * @param source - reads the current settings section; called per request.
+     */
+    constructor(ctx: Context, source: () => AdvancedSidebarSettings);
+    /**
+     * Report what the Tasks panel may do on this Host.
+     * @returns availability plus the two per-verb permissions.
+     */
+    describe(): CapabilityState & {
+        canKill: boolean;
+        canReadOutput: boolean;
+    };
+    /**
+     * Stop one live task.
+     *
+     * The registry marks a killed record reported, which suppresses the completion notice its
+     * producer would otherwise open a model turn to deliver. That is the correct trade for a person
+     * pressing Stop — the work is being cancelled on their authority, not the model's — and it is why
+     * this verb is gated by `allowTaskKill` rather than always on.
+     * @param request - the owning session and the task id.
+     * @returns what the registry did, or a classified failure.
+     */
+    kill(request: TaskKillRequest): Promise<TaskKillResult>;
+    /**
+     * Read one task's output, or say why it is withheld.
+     * @param request - the owning session and the task id.
+     * @returns the accumulated output, or a classified failure.
+     */
+    output(request: TaskOutputRequest): Promise<TaskOutputResult>;
+    /** Drop retained output. Called from the service's teardown effect. */
+    dispose(): void;
+    /**
+     * Drain whatever the registry will still hand over and append it to the retained text.
+     * @param sessionId - the owning session.
+     * @param taskId - the task id.
+     */
+    private absorb;
+    /**
+     * Resolve the registry, the owning agent, and the branded job id together.
+     * @param sessionId - the owning session, as the browser spelled it.
+     * @param taskId - the task id, as the browser spelled it.
+     * @returns the bound handles, or the failure to return.
+     */
+    private bind;
+}

package/types/host/terminals.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Panel terminals: interactive shells this plugin owns, allocated straight from
+ * `ctx.subprocess.spawnTerminal`.
+ *
+ * Deliberately NOT `ctx.terminals`. That registry's sessions are owner-fenced to an `Agent` and are
+ * the model's working terminals; a person opening the Terminal panel is not the model, and joining
+ * them would let a human's keystrokes land in a session the model believes it controls. These are
+ * separate shells with the panel's own lifetime.
+ *
+ * There is no host-to-client push channel available to an out-of-tree plugin, so output is read by
+ * offset: the browser polls, and the offset it holds is the whole-stream position it has already
+ * rendered. That also makes a reconnecting panel replay exactly the retained scrollback rather than
+ * an empty screen.
+ * @module @achasoft/dsh-advanced-sidebar/host/terminals
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AdvancedSidebarSettings, CapabilityState, TerminalAckResult, TerminalCloseRequest, TerminalOpenRequest, TerminalOpenResult, TerminalReadRequest, TerminalReadResult, TerminalSignalRequest, TerminalWriteRequest } from './types.ts';
+/**
+ * Owns every panel terminal in the process. One instance is created by the service and disposed
+ * with it, which is what guarantees no shell outlives the plugin.
+ */
+export declare class PanelTerminals {
+    private readonly ctx;
+    private readonly source;
+    private readonly records;
+    private closing;
+    /**
+     * @param ctx - Host context carrying the subprocess and filesystem capabilities.
+     * @param source - reads the current settings section; called per request.
+     */
+    constructor(ctx: Context, source: () => AdvancedSidebarSettings);
+    /**
+     * Report whether a panel terminal can be allocated on this Host.
+     * @returns availability plus the shell that would answer.
+     */
+    describe(): CapabilityState;
+    /**
+     * Allocate one terminal in a workspace.
+     * @param request - the directory and the panel's measured geometry.
+     * @param signal - cancellation of the allocation; a published terminal owns its later lifetime.
+     * @returns the handle, or a classified failure.
+     */
+    open(request: TerminalOpenRequest, signal?: AbortSignal): Promise<TerminalOpenResult>;
+    /**
+     * Read output from a caller-owned offset.
+     * @param request - the handle and the offset already rendered.
+     * @returns the delta and the process state, or a classified failure.
+     */
+    read(request: TerminalReadRequest): TerminalReadResult;
+    /**
+     * Send keystrokes.
+     * @param request - the handle and the text to deliver verbatim.
+     * @returns settlement, or a classified failure.
+     */
+    write(request: TerminalWriteRequest): Promise<TerminalAckResult>;
+    /**
+     * Deliver a signal to the terminal's foreground process group.
+     * @param request - the handle and the signal.
+     * @returns settlement, or a classified failure.
+     */
+    signal(request: TerminalSignalRequest): Promise<TerminalAckResult>;
+    /**
+     * Close one terminal and forget it.
+     * @param request - the handle.
+     * @returns settlement, or a classified failure.
+     */
+    close(request: TerminalCloseRequest): Promise<TerminalAckResult>;
+    /**
+     * Terminate every terminal and refuse new ones. Called from the service's teardown effect.
+     * @returns after every terminal session has settled.
+     */
+    disposeAll(): Promise<void>;
+    /**
+     * The shell a new terminal starts: the configured one, then `$SHELL`, then the platform default.
+     * @returns an executable name or path.
+     */
+    private shell;
+    /**
+     * Drain one terminal's output into its retained scrollback and record its settlement.
+     *
+     * Attached at allocation rather than at first read: a shell prints its prompt immediately, and a
+     * stream nobody is reading would otherwise apply backpressure until the panel polled.
+     * @param record - the freshly registered terminal.
+     */
+    private collect;
+}