@linxin666/dsh-client-ui-task-board 0.4.4 → 0.4.6

package/lib/types/core/workspace-target.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Workspace targeting for cards that pin none.
+ *
+ * The Host answers two questions here instead of leaving them to
+ * `session.create`, whose own fallback is the Host process working directory
+ * (the desktop app's profile directory): which workspace a root card inherits
+ * from the session that created it, and which workspace an unpinned run lands
+ * in when nothing could be inherited.
+ *
+ * Structural types only — the Host's `Workspace` entity satisfies them — so the
+ * browser program compiles this module without importing an SDK value.
+ *
+ * @module dsh-task-board/core/workspace-target
+ */
+/** The workspace facts these rules read (a `Workspace` entity subset). */
+export interface WorkspaceCandidate {
+    /** Stable workspace record id. */
+    readonly id: string;
+    /** ISO-8601 instant of the workspace's last durable mutation. */
+    readonly updatedAt: string;
+    /** Header-validated session ids the workspace owns, most recent first. */
+    readonly sessionIds: readonly string[];
+}
+/**
+ * The workspace that owns one session.
+ * @param items - the deployment's workspaces.
+ * @param sessionId - the session whose workspace is requested.
+ * @returns the owning workspace id, or undefined when none claims the session.
+ */
+export declare function workspaceOwningSession(items: readonly WorkspaceCandidate[], sessionId: string): string | undefined;
+/**
+ * The workspace the board treats as most recently used: the one whose record
+ * changed last. Attaching a session stamps that instant, so the newest stamp
+ * tracks where the user most recently opened or resumed a session. The
+ * deployment's own list order breaks ties, and a stamp that does not parse
+ * never outranks one that does; a registry whose stamps are all unreadable
+ * falls back to list order rather than to "no workspace at all".
+ * @param items - the deployment's workspaces.
+ * @returns the most recently used workspace id, or undefined when there is none.
+ */
+export declare function mostRecentWorkspaceId(items: readonly WorkspaceCandidate[]): string | undefined;

package/lib/types/host/agent-tools.d.ts

@@ -8,7 +8,7 @@ export interface TaskBoardToolHost {
     /** Current board snapshot (tasks + scheduler + power + deployment constants). */
     snapshot(): TaskBoardSnapshot;
     /** Submit one confirmed Host action; returns the resulting snapshot. */
-    apply(requestId: string, action: TaskBoardAction, initiator?: string): TaskBoardSnapshot;
+    apply(requestId: string, action: TaskBoardAction, initiator?: string): TaskBoardSnapshot | Promise<TaskBoardSnapshot>;
 }
 /** Registered tool names, in registration order. */
 export declare const TASK_BOARD_TOOL_NAMES: readonly ["task_board_list", "task_board_get", "task_board_create", "task_board_update", "task_board_set_parent", "task_board_run", "task_board_manage", "task_board_schedule"];

package/lib/types/host/extension-registry.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Host-side extension registry: the one place that admits external providers,
+ * negotiates the contract version, gates them on the board's own enable state,
+ * fans board events out to them, and routes dispatched provider actions back.
+ *
+ * Failure policy (mirrors the board's plugin philosophy): a provider that
+ * throws, mis-declares its version, or disables itself degrades only its own
+ * surface. The board keeps serving; the registry records what it refused.
+ *
+ * @module dsh-task-board/host/extension-registry
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { HostTaskLedger } from '../host-ledger.ts';
+import type { TaskBoardAction, TaskBoardSnapshot } from '../protocol.ts';
+import { type TaskBoardExecutionSettledEvent, type TaskBoardExtension, type TaskBoardExtensionActionRequest, type TaskBoardExtensionPayload, type TaskBoardStatusChangedEvent, type TaskBoardTaskDeletedEvent } from '../core/extension.ts';
+/** Diagnosable refusal raised by the registry and the capability face. */
+export declare class TaskBoardExtensionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Logging seat the registry uses; a deployment may supply its own. */
+export interface TaskBoardExtensionLogger {
+    warn(message: string, ...rest: unknown[]): void;
+    error(message: string, ...rest: unknown[]): void;
+}
+/** The deployment's model-visible tool registry, resolved lazily. */
+export interface TaskBoardExtensionToolRegistry {
+    register(definition: ToolDefinition): () => void;
+}
+/** Applies one board action with every board gate intact (never an extension action). */
+export type TaskBoardActionApplier = (action: Exclude<TaskBoardAction, {
+    kind: 'extension-action';
+}>, initiator?: string) => TaskBoardSnapshot;
+/** Registry dependencies. */
+export interface TaskBoardExtensionRegistryOptions {
+    ledger: HostTaskLedger;
+    /** Apply an action through the board service (gates, run dispatch, schedule). */
+    apply?: TaskBoardActionApplier;
+    /** Resolve the deployment's tool registry; absent loses the tool surface only. */
+    toolRegistry?: () => TaskBoardExtensionToolRegistry | undefined;
+    now?: () => number;
+    uuid?: () => string;
+    logger?: TaskBoardExtensionLogger;
+}
+export declare class TaskBoardExtensionRegistry {
+    private readonly entries;
+    private readonly ledger;
+    private readonly applyAction;
+    private readonly now;
+    private readonly uuid;
+    private readonly logger;
+    private toolResolver;
+    /** Board master switch (enabled config); providers start only while it is on. */
+    private boardEnabled;
+    private disposed;
+    constructor(options: TaskBoardExtensionRegistryOptions);
+    /**
+     * Pin (or replace) the deployment's tool registry. A registry that appears
+     * after a provider started is picked up here, which is what keeps the tool
+     * surface alive across the board's own late service resolution.
+     */
+    setToolRegistry(resolver: (() => TaskBoardExtensionToolRegistry | undefined) | undefined): void;
+    /** Apply the board's master switch; providers start and stop with it. */
+    setEnabled(enabled: boolean): void;
+    /** Whether the board currently runs a given extension (board x extension). */
+    isActive(extensionId: string): boolean;
+    /**
+     * Admit one provider. Idempotent by id: a second registration of the same id
+     * is a no-op that returns the same release handle. A contract-version
+     * mismatch is refused visibly (logged and thrown) without disturbing the
+     * board or any other provider.
+     * @param extension - the provider to admit.
+     * @returns a disposer releasing the registration (idempotent).
+     */
+    registerExtension(extension: TaskBoardExtension): () => void;
+    /** Remove one provider; its provider-side work stops and its payload stays stored. */
+    unregister(extensionId: string): void;
+    /**
+     * Route one dispatched provider action. Refuses visibly when the extension is
+     * unknown, currently gated off, or does not implement the action.
+     */
+    handleAction(request: TaskBoardExtensionActionRequest): Promise<unknown>;
+    /** Published summaries of currently running providers, keyed by extension id. */
+    published(): Record<string, TaskBoardExtensionPayload>;
+    /** Fan a status change out to every running provider, isolated per callback. */
+    emitStatusChanged(event: TaskBoardStatusChangedEvent): void;
+    /** Fan an execution settlement out to every running provider. */
+    emitExecutionSettled(event: TaskBoardExecutionSettledEvent): void;
+    /** Fan a task deletion out to every running provider. */
+    emitTaskDeleted(event: TaskBoardTaskDeletedEvent): void;
+    /** Stop every provider and release the registry (idempotent). */
+    dispose(): void;
+    private emit;
+    /** Start or stop one entry against the current board + extension gate. */
+    private reconcile;
+    private startEntry;
+    private stopEntry;
+    /** (Re)register every buffered tool against the current tool registry. */
+    private syncTools;
+    private disposeTools;
+    private assertActive;
+    /** Build the per-extension capability face. */
+    private capabilities;
+    private createTask;
+    private patchContent;
+    private setStatus;
+    private linkedTasks;
+    private writeIntegration;
+    private publish;
+    private registerTool;
+}

package/lib/types/host/llm-dispatch.d.ts

@@ -0,0 +1,63 @@
+/**
+ * One-shot model dispatch for the board's Host half.
+ *
+ * The board makes two one-shot model calls: the goal-acceptance judge
+ * (`verification-runner.ts`) and the "parse pasted text" action
+ * (`host-ai.ts`). Both call the official `llm` service, and both must call it
+ * the way the official agent loop does.
+ *
+ * The runtime exposes two entry points with the same name shape. The public
+ * `stream(options)` is a single-argument convenience method, and it is an
+ * ordinary instance property — any plugin may overwrite it. The registration
+ * bound path `prepareCall(config)` returns a one-shot handle whose
+ * `stream(request)` reaches the adapter through the runtime's internal
+ * dispatch instead, and `ctx.on('llm/stream')` remains the supported seam every
+ * extension is expected to register on.
+ *
+ * A third-party provider plugin that patched `llm.stream` with the waterfall
+ * listener signature `(options, next)` broke every caller that used the public
+ * method: `llm.stream(options)` invoked the listener with `next === undefined`,
+ * so the guard's `for await (const chunk of next())` raised
+ * `TypeError: next(...) is not a function or its return value is not async
+ * iterable`. The agent loop was unaffected because it already dispatches
+ * through `prepareCall(...).stream(...)`; the board's two one-shot calls were
+ * not, and each completed acceptance was recorded as an anomaly
+ * ("验收异常（裁判请求失败）") after two judge attempts.
+ *
+ * Dispatching through the prepared call fixes that at the owner: the board no
+ * longer depends on a mutable instance property that a plugin may legitimately
+ * replace, and a plugin that registers on `llm/stream` is still invoked. The
+ * public method remains the fallback for a runtime that exposes no
+ * `prepareCall` at all, so an older or proxied service keeps working.
+ */
+import { type GenerateOptions, type LlmRuntime, type StreamChunk } from '@deepseek-ai/dsh-llm';
+/** The request fields the board adds around a call config. */
+export type OneShotRequest = Pick<GenerateOptions, 'messages' | 'signal'> & Pick<GenerateOptions, 'system'>;
+/**
+ * The call config as this board's own domain types carry it.
+ *
+ * `VerificationRoute.reasoningEffort` and the parse route are plain strings (the
+ * catalog publishes effort ids as strings), while the SDK brands them
+ * nominally; the single crossing is branded here so no caller repeats the
+ * assertion.
+ */
+export interface OneShotCallConfig {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+/**
+ * Open one one-shot model stream on the registration-bound dispatch path.
+ *
+ * The call-config fields must travel inside `config` (not the request): the
+ * prepared handle refuses a request whose config fields differ from the ones it
+ * resolved, so the request carries only messages, signal, and the optional
+ * one-shot system prompt.
+ * @param llm - the Host's llm service.
+ * @param config - provider/model route plus the caller's sampling controls.
+ * @param request - the assembled messages and cancellation for this call.
+ * @returns the chunk stream, including any registered `llm/stream` listener.
+ */
+export declare function openOneShotStream(llm: LlmRuntime, config: OneShotCallConfig, request: OneShotRequest): Promise<AsyncIterable<StreamChunk>>;

package/lib/types/host/verification-gate.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Goal acceptance gate: the board's evaluator-backed certification of a goal
+ * completion claim.
+ *
+ * The gate sits on the official tool pre-execute lifecycle and intercepts the
+ * one call that ends a goal run — `update_goal` with `action: 'complete'`
+ * — BEFORE it takes effect. This is why the board does not ask the agent to
+ * verify itself: the tool call that finishes the goal is refused until a
+ * matching acceptance pass record exists, so no prompt wording and no
+ * self-report can route around it.
+ *
+ * Semantics owned here:
+ * - one acceptance cycle per EXECUTION, spent at most twice: the first failure
+ *   returns its findings to the fixing agent, the second ends the cycle;
+ * - a repeated completion call during a repair, a new automatic goal round, a
+ *   plugin reload and a Host restart all reuse the same cycle rather than
+ *   resetting it (the budget is persisted on the execution record);
+ * - an anomaly (timeout, authentication, unparseable answer, an unusable judge
+ *   route) is recorded separately from a quality verdict and is never treated
+ *   as one;
+ * - exhausting the anomaly budget does NOT judge the card: an environment that
+ *   cannot answer is not the work failing, so the cycle is held open with no
+ *   judge call until a user clears the recorded anomalies (issue #1828);
+ * - an attempt the time budget ends before any verdict is recorded as its own
+ *   stage and charged to no budget at all (issue #1828);
+ * - an INVALID acceptance (a veto whose required evidence is missing,
+ *   unlocatable, or aimed at the empty-work baseline) is recorded in its own
+ *   stage, spends its OWN bounded budget, and never consumes a quality attempt
+ *   or fails the card; when that budget is spent the cycle is held for a human
+ *   exactly like a spent anomaly budget;
+ * - concurrent completion calls for one execution share one acceptance.
+
+ * The validity check itself is program-level (`assessAcceptanceValidity` in
+ * `core/verification.ts`), applied after the judge answers and BEFORE any
+ * quality verdict is written: a stronger prompt alone could not enforce it.
+ */
+import type { PreToolDecision } from '@deepseek-ai/dsh-tools';
+import type { LlmRuntime } from '@deepseek-ai/dsh-llm';
+import { type WorkspaceChangeSource } from './workspace-evidence.ts';
+import type { HostTaskLedger } from '../host-ledger.ts';
+/** The subset of the official goal service this gate drives. */
+export interface GoalFace {
+    get(agent: unknown): {
+        id: string;
+        revision: number;
+        objective: string;
+    } | undefined;
+    block(agent: unknown, ref: {
+        id: string;
+        revision: number;
+    }, reason: {
+        code: string;
+        message: string;
+    }): unknown;
+}
+/** Everything the gate needs from its owner. */
+export interface GoalVerificationGateDeps {
+    ledger: HostTaskLedger;
+    /** Resolve the optional model runtime lazily (it may activate later). */
+    llm?: () => LlmRuntime | undefined;
+    /** Resolve the optional goal service lazily. */
+    goals?: () => GoalFace | undefined;
+    /**
+     * Resolve the optional host change service lazily. Absent (or a deployment
+     * that serves none) simply means the judge sees the trajectory alone.
+     */
+    workspaceChanges?: () => WorkspaceChangeSource | undefined;
+    /**
+     * Ceiling of one judge request, read per acceptance (a row setting). Absent
+     * keeps the default, so a programmatic mount still judges.
+     */
+    callTimeoutMs?: () => number;
+    /**
+     * Total ceiling of one acceptance attempt, read per acceptance (a row
+     * setting). Absent keeps the default.
+     */
+    budgetMs?: () => number;
+    logger: {
+        warn(message: string, ...rest: unknown[]): void;
+    };
+    now?: () => number;
+}
+/** The shape of one tool pre-execution the gate inspects. */
+export interface GateExecution {
+    name: string;
+    arguments: unknown;
+    agent?: unknown;
+    signal: AbortSignal;
+}
+/**
+ * Create the goal acceptance gate.
+ * @param deps - the ledger, the model runtime, the goal service and the settings.
+ * @returns the `tools/pre-execute` listener body (without the waterfall next()).
+ */
+export declare function createGoalVerificationGate(deps: GoalVerificationGateDeps): (exec: GateExecution) => Promise<PreToolDecision | undefined>;

package/lib/types/host/verification-runner.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Goal acceptance runner: evidence assembly and the judge calls of one
+ * acceptance attempt.
+ *
+ * Lives in the host half because it needs the live session event log and the
+ * official `llm` service; every rule it applies (criteria, scale, tags,
+ * thresholds, budgets, caps) comes from `../core/verification.ts`, which mirrors
+ * the installed dsh-llm-verifier 0.8.4 default final acceptance.
+ */
+import { type LlmRuntime } from '@deepseek-ai/dsh-llm';
+import { type VerificationAttempt, type VerificationRoute, type VerificationUsage } from '../core/verification.ts';
+/** Largest trace handed to the judge, mirroring the verifier's default cap. */
+export declare const VERIFICATION_MAX_TRACE_CHARS = 80000;
+/** Largest single trace entry; one huge tool result must not eat the budget. */
+export declare const VERIFICATION_MAX_ENTRY_CHARS = 4000;
+/** Largest per-finding text kept from one judge answer. */
+export declare const VERIFICATION_MAX_FINDING_CHARS = 400;
+/** Largest verbatim citation kept from one finding. */
+export declare const VERIFICATION_MAX_QUOTE_CHARS = 600;
+/** Largest requirement/observation/gap statement kept from one finding. */
+export declare const VERIFICATION_MAX_PROBLEM_CHARS = 400;
+/** Structured findings kept per judge answer and per acceptance. */
+export declare const VERIFICATION_MAX_FINDINGS_PER_CALL = 3;
+export declare const VERIFICATION_MAX_FINDINGS = 12;
+/**
+ * Default ceiling of ONE judge request. The effective ceiling is a row setting
+ * (`goalVerificationCallTimeoutSeconds`), read live by the gate, because 120s was
+ * tight for a reasoning model reading an 80,000 character trace with a 16,384
+ * token output cap: every timeout it produced was charged as an acceptance
+ * anomaly against a budget that then failed the card.
+ */
+export declare const VERIFICATION_CALL_TIMEOUT_MS = 150000;
+export declare const VERIFICATION_MAX_TOKENS = 16384;
+export declare const VERIFICATION_TEMPERATURE = 0.2;
+export declare const VERIFICATION_REQUEST_ATTEMPTS = 3;
+/** Redaction patterns, mirrored from the verifier's defaults. */
+export declare const VERIFICATION_REDACT_PATTERNS: readonly string[];
+/** Why one acceptance could not produce a verdict. */
+export type VerificationErrorKind = 'route-unavailable' | 'timeout' | 'auth' | 'parse' | 'request' | 'aborted' | 'budget';
+/**
+ * The time one acceptance attempt may still spend.
+ *
+ * `deadline` is the instant the whole attempt runs out; `callTimeoutMs` is the
+ * ceiling of a single judge call. The pair is what ties the retry budget to the
+ * acceptance budget: a call is not started unless its own ceiling still fits
+ * inside what is left, because starting one the outer budget will abort anyway
+ * only burns wall time and turns a slow machine into an anomaly.
+ */
+export interface AcceptanceBudget {
+    /** Absolute instant (ms epoch) the acceptance attempt runs out at. */
+    deadline: number;
+    /** Ceiling of one judge call in milliseconds. */
+    callTimeoutMs: number;
+    /** Clock the caller runs on, injected so tests drive it deterministically. */
+    now: () => number;
+}
+/** An acceptance anomaly: never a quality verdict, always recorded as one. */
+export declare class VerificationError extends Error {
+    readonly kind: VerificationErrorKind;
+    readonly usage: VerificationUsage;
+    constructor(kind: VerificationErrorKind, message: string, usage?: VerificationUsage, options?: {
+        cause?: unknown;
+    });
+}
+/** Fresh zeroed usage counters. */
+export declare function emptyUsage(): VerificationUsage;
+/** Structural view of one session event, as the host log carries it. */
+interface RawEvent {
+    type?: unknown;
+    seq?: unknown;
+    time?: unknown;
+    data?: unknown;
+}
+/** Read one session's events across the shapes the SDK cohort exposes. */
+export declare function sessionEvents(session: unknown): readonly RawEvent[];
+/** Evidence assembled for one acceptance attempt. */
+export interface AcceptanceEvidence {
+    problem: string;
+    trace: string;
+    entries: number;
+    fromSeq?: number;
+    toSeq?: number;
+    omittedCharacters: number;
+    hash: string;
+}
+/**
+ * Assemble the evidence one acceptance judges.
+ *
+ * The window starts at the execution's own `startedAt`, never at the session's
+ * first event: a reused session carries the history of earlier executions, and
+ * those runs must not be judged as this one's work. Only observed output is
+ * rendered — tool calls with their arguments and their results, assistant
+ * prose, goal round markers and team messages — and the result is redacted and
+ * capped before it ever reaches a judge.
+ * @param session - the live session of the execution.
+ * @param problem - the execution's composed prompt, shown as the task statement.
+ * @param startedAt - the instant the execution opened (ms epoch).
+ * @returns the bounded, redacted evidence.
+ */
+/**
+ * The session events inside one execution's own window.
+ *
+ * A reused session carries the history of earlier executions; only the events
+ * at or after this execution's start belong to the work being judged.
+ * @param session - the live session.
+ * @param startedAt - the execution's start instant (ms epoch).
+ * @returns the events of this execution, oldest first.
+ */
+export declare function evidenceEvents(session: unknown, startedAt: number): readonly RawEvent[];
+export declare function collectEvidence(session: unknown, problem: string, startedAt: number): AcceptanceEvidence;
+/** The verdict of one acceptance attempt. */
+export interface AcceptanceResult {
+    attempt: VerificationAttempt;
+}
+/**
+ * Run one acceptance: every criterion is judged twice, the odd round with the
+ * A/B slots swapped, and the per-round scores are mapped back and averaged per
+ * criterion.
+ * @param input - the judge route, evidence, threshold, time budget and cancellation.
+ * @returns the recorded attempt (quality verdict, anomaly, or budget stop).
+ */
+export declare function runAcceptance(input: {
+    llm: LlmRuntime;
+    route: VerificationRoute;
+    evidence: AcceptanceEvidence;
+    threshold: number;
+    index: number;
+    signal: AbortSignal;
+    /** Instant (ms epoch) the attempt runs out at; defaults to now plus the default budget. */
+    deadline?: number;
+    /** Ceiling of one judge call; defaults to {@link VERIFICATION_CALL_TIMEOUT_MS}. */
+    callTimeoutMs?: number;
+    /** Host-observed workspace changes, rendered as the prompt's reference context. */
+    context?: string;
+    /** How many changed files that context shows. */
+    workspaceFiles?: number;
+    now?: () => number;
+}): Promise<AcceptanceResult>;
+export {};

package/lib/types/host/workspace-evidence.d.ts

@@ -0,0 +1,53 @@
+/** The subset of the host change service this module drives. */
+export interface WorkspaceChangeSource {
+    summary(sessionId: string, seq: number): unknown;
+    diff(sessionId: string, seq: number, index: number, signal: AbortSignal): Promise<unknown>;
+}
+/** One session event, as the host log carries it. */
+interface RawEvent {
+    type?: unknown;
+    seq?: unknown;
+}
+/** How many changed files one evidence block renders. */
+export declare const MAX_WORKSPACE_FILES = 8;
+/** Character ceiling for the whole rendered block. */
+export declare const WORKSPACE_EVIDENCE_MAX_CHARS = 24000;
+/** Character ceiling for one file's rendered comparison. */
+export declare const WORKSPACE_EVIDENCE_MAX_FILE_CHARS = 6000;
+/**
+ * Resolve the optional host change service from a context-like object.
+ * @param ctx - anything exposing @@get(name)@@.
+ * @returns the service, or undefined when this deployment serves none.
+ */
+export declare function probeWorkspaceChanges(ctx: {
+    get(name: string): unknown;
+}): WorkspaceChangeSource | undefined;
+/** The sequence of the newest change event inside the reviewed window. */
+export declare function latestChangeEvent(events: readonly RawEvent[]): {
+    seq: number;
+    turn?: number;
+} | undefined;
+/**
+ * Render the host's own record of what the reviewed window changed.
+ *
+ * Bounded twice — at most {@link MAX_WORKSPACE_FILES} files, and a shared
+ * character budget split across them — so one enormous generated file cannot
+ * crowd out every other change. Every failure degrades to less evidence (or an
+ * empty block) instead of an error, because the acceptance being prepared must
+ * still reach a verdict.
+ * @param events - session events already bounded to the execution's window.
+ * @param sessionId - the session whose changes these are.
+ * @param source - the probed host service.
+ * @param options - budget, cancellation and the diagnostic sink.
+ * @returns the rendered block plus how many files it shows.
+ */
+export declare function renderWorkspaceEvidence(events: readonly RawEvent[], sessionId: string, source: WorkspaceChangeSource, options: {
+    signal: AbortSignal;
+    warn?: (message: string) => void;
+    maxChars?: number;
+}): Promise<{
+    text: string;
+    files: number;
+    hash: string;
+}>;
+export {};