@try-works/dsh-recursive-mode 0.2.4 → 0.3.0

package/lib/delegation.d.ts

@@ -1,8 +1,52 @@
+/**
+ * Opaque handle to the live direct-parent Agent. The live continuable service
+ * authorizes by EXACT live object identity — `ctx.agents.get(parent.id) ===
+ * parent` (authorizeLineage), `ancestry.has(parent)` (interrupt/drain), and a
+ * `WeakSet` of live ancestry — so this must be the real live `Agent`, never a
+ * structural `{ id }` copy. The seam only ever reads `id`/`session.header.cwd`
+ * for attribution, and never serializes or inspects the live object.
+ */
+export interface SubagentParentHandle {
+    readonly id?: string;
+    readonly session?: {
+        readonly header?: {
+            readonly cwd?: string;
+        };
+    };
+}
+/** Durable identity of one continuable child session (string-branded in the host). */
+export type ContinuableChildId = string;
+/** Durable identity of one accepted inbox message (string-branded in the host). */
+export type ContinuableMessageId = string;
+/**
+ * Attribution for a model coordinator's follow-up to one of its children (the
+ * live `CoordinatorMessageSource` subset — see subagent/src/continuation.ts).
+ */
+export interface CoordinatorSourceLike {
+    readonly kind: 'coordinator';
+    readonly form: 'relay';
+    readonly senderSessionId: string;
+}
+/** Uniform outcome for the interrupt/drain kill-switch helpers. */
+export interface ContinuableOpResult {
+    ok: boolean;
+    reason?: string;
+}
 /** Minimal host-realm contract for ctx.subagents (the seam we call). */
 export interface SubagentsRuntimeLike {
     start(name: string, request: SubagentStartRequestLike): Promise<SubagentResultLike>;
     getProvider?(name: string): unknown;
     list?(): unknown;
+    /** T4: continuable child lifecycle (startContinuable / followup / interrupt / drain). */
+    startContinuable?(spec: ContinuableStartSpecLike): Promise<ContinuableStartLike>;
+    /** The parent MUST be the exact live Agent (object-identity authority), never a `{ id }` copy. */
+    followup?(parent: SubagentParentHandle, childId: ContinuableChildId, content: readonly {
+        type: 'text';
+        text: string;
+    }[], options: SubagentFollowupOptionsLike): Promise<ContinuableMessageId>;
+    interrupt?(targetSessionId: ContinuableChildId, authority: SubagentInterruptAuthorityLike): void;
+    drainContinuableChildren?(parent: SubagentParentHandle, childIds: readonly ContinuableChildId[]): Promise<void>;
+    drainContinuableDescendants?(parents: readonly SubagentParentHandle[]): Promise<void>;
 }
 export interface SubagentStartRequestLike {
     prompt: unknown[];
@@ -37,6 +81,130 @@ export declare function delegate(input: {
     provider: string;
     request: SubagentStartRequestLike;
 }): Promise<SubagentResultLike>;
+/**
+ * T4: continuable-child delegation — ONE durable child receives the initial
+ * prompt (startContinuable), each REVISE is delivered as a followup to the SAME
+ * child (FIFO, working set retained), and the parent observes each round's
+ * settlement through the injected `awaitRoundResult` seam (in live usage the
+ * child's settlement lands in the parent's inbox — `reportFrom` is the
+ * CHILD-side API, so the parent-side loop collects via settlement, not by
+ * calling it). A hung reviewer is cancelled with `interruptContinuable`
+ * (keepInbox: the child's pending inbox survives). Falls back to one-shot
+ * `delegate` when the seam has no continuable methods.
+ */
+/** What the caller asks for when starting a continuable background child (structural subset). */
+export interface ContinuableStartSpecLike {
+    /** The `ctx.subagents` provider whose continuable-creation capability establishes the child. */
+    readonly provider: string;
+    /** The initial delegation's short `description`, persisted as the child's creation label. */
+    readonly label: string;
+    /** Optional caller-reserved child identity. */
+    childId?: ContinuableChildId;
+    /** The delegation request (prompt + parent + toolFilter + maxDepth; no label/signal/outputSchema). */
+    readonly request: Omit<SubagentStartRequestLike, 'label' | 'signal' | 'outputSchema'>;
+    /** Caller cancellation, owning the operation only until inbox acceptance. */
+    readonly signal?: AbortSignalLike;
+}
+/** Minimal cancellation shape (a live AbortSignal satisfies it). */
+export interface AbortSignalLike {
+    readonly throwIfAborted: () => void;
+}
+/** Identities returned once a continuable child accepted its initial prompt. */
+export interface ContinuableStartLike {
+    /** The durable child session id, stable across activations. */
+    readonly childId: ContinuableChildId;
+    /** The accepted initial prompt's inbox message id. */
+    readonly messageId: ContinuableMessageId;
+}
+/** Options for following up with one continuable child (structural subset). */
+export interface SubagentFollowupOptionsLike {
+    /** Durable attribution retained on the delivered message. */
+    readonly source: CoordinatorSourceLike;
+    /** Caller cancellation, owning the operation only until inbox acceptance. */
+    readonly signal?: AbortSignalLike;
+}
+/** Authority under which one interrupt request is admitted. */
+export type SubagentInterruptAuthorityLike = {
+    readonly kind: 'user';
+    readonly parentSessionId: string;
+} | {
+    readonly kind: 'ancestor';
+    readonly agent: SubagentParentHandle;
+};
+/** One round of a continuable child: the delivered text plus the observed outcome. */
+export interface ContinuableRoundLike {
+    /** The message text delivered as this round's user prompt. */
+    text: string;
+    /** The child's observed outcome for this round. */
+    result?: SubagentResultLike;
+    /** True when this round's verdict was REVISE (a repair followup followed). */
+    revise?: boolean;
+    /** The repair instruction delivered in the followup (only when revise). */
+    repair?: string;
+}
+/** The full T4 delegation outcome. */
+export interface ContinuableDelegationLike {
+    ok: boolean;
+    reason?: string;
+    /** The durable child session id (stable across rounds). */
+    childId?: ContinuableChildId;
+    /** Inbox message ids: [initial acceptance, ...followups]. */
+    messageIds?: ContinuableMessageId[];
+    rounds: ContinuableRoundLike[];
+    /** Final outcome accepted (last verdict APPROVE + result accepted). */
+    accepted: boolean;
+    /** True when the fallback one-shot `delegate()` was used (no continuable seam). */
+    fellBackToOneShot?: boolean;
+}
+/** Verdict vocabulary shared by T3/T4 (matches the delegated review schema). */
+export type DelegationVerdict = 'APPROVE' | 'REVISE' | 'REJECT';
+/** Read the verdict from a review-schema structured result (pure). */
+export declare function readVerdictFromStructured(result: SubagentResultLike): DelegationVerdict;
+/** Read the repair instruction from a review-schema structured result (pure). */
+export declare function readRepairFromStructured(result: SubagentResultLike): string;
+/**
+ * Run a multi-round delegated task on ONE durable continuable child:
+ * 1. `startContinuable` (initial prompt) — `start()` is never called.
+ * 2. `awaitRoundResult` observes the child's settlement for that round.
+ * 3. On REVISE: `followup` delivers the repair instruction to the SAME child.
+ * 4. On APPROVE/REJECT: finish (accepted only when the verdict is APPROVE and
+ *    the result evaluates as accepted).
+ *
+ * `awaitRoundResult(childId, messageId)` is the ONLY parent-side observation
+ * seam: in live usage it waits for the child's settlement notice (the child's
+ * `reportFrom` lands in the parent's inbox); in tests it is a fake queue.
+ */
+export declare function delegateContinuable(input: {
+    subagents: SubagentsRuntimeLike;
+    provider: string;
+    label: string;
+    prompt: string;
+    parent?: SubagentParentHandle;
+    toolFilter?: unknown;
+    maxDepth?: number;
+    childId?: ContinuableChildId;
+    maxRounds?: number;
+    readVerdict?: (result: SubagentResultLike) => DelegationVerdict;
+    readRepair?: (result: SubagentResultLike) => string | undefined;
+    awaitRoundResult?: (childId: ContinuableChildId, messageId: ContinuableMessageId) => Promise<SubagentResultLike | null>;
+}): Promise<ContinuableDelegationLike>;
+/**
+ * T4 kill switch: interrupt one live continuable child's current turn. Admission
+ * is synchronous, the effect asynchronous, and the child's pending inbox is
+ * preserved (keepInbox semantics) — a followup later resumes the parked queue.
+ */
+export declare function interruptContinuable(subagents: SubagentsRuntimeLike, childId: ContinuableChildId, parentSessionId: string): ContinuableOpResult;
+/**
+ * T4 closeout: release one continuable child (host drains its Activation and
+ * disposes its handle). No-op when the seam lacks the method (one-shot hosts).
+ */
+export declare function drainContinuableChildren(subagents: SubagentsRuntimeLike, parent: SubagentParentHandle, childIds: readonly ContinuableChildId[]): Promise<ContinuableOpResult>;
+/**
+ * T4 closeout (host teardown path): release every continuable descendant below
+ * the given live parents (mirrors the live `drainContinuableDescendants`).
+ * No-op when the seam lacks the method; the host owns this at session teardown.
+ */
+export declare function drainContinuableDescendants(subagents: SubagentsRuntimeLike | null, parents: readonly SubagentParentHandle[]): Promise<ContinuableOpResult>;
 export interface Reference {
     path: string;
     lineRange?: string;

package/lib/enforcement.d.ts

@@ -14,6 +14,7 @@ export declare const DEFAULT_ENFORCEMENT: EnforcementConfig;
  */
 export type ToolGuardDecision = {
     kind: 'allow';
+    warn?: string;
 } | {
     kind: 'deny';
     reason: string;
@@ -27,6 +28,13 @@ export interface ToolExecLike {
     agent?: unknown;
 }
 export declare function evaluateToolGuard(exec: ToolExecLike, worktreeRoot: string, activeRunId: string, mode?: EnforcementMode): ToolGuardDecision;
+/**
+ * T6 (approval ask→policy bridge): an `ask` decision must never be a silent
+ * allow. Under `strict` it coerces to `deny`; under `advisory` it stays `allow`
+ * but flags a `warn` so the caller never lets it through unlogged. Non-ask
+ * decisions pass through unchanged.
+ */
+export declare function coerceAskToDecision(decision: ToolGuardDecision, mode?: EnforcementMode): ToolGuardDecision;
 /**
  * Layer 8 - fs/observed lock-tamper detection.
  * A locked *.md whose observed version differs from the stored LockHash is

package/lib/goals-projection.d.ts

@@ -0,0 +1,92 @@
+/**
+ * goals-projection.ts (T1, STRENGTHENING-PLAN): project a recursive run into the
+ * native `goals` service so the run is a first-class durable, resumable,
+ * blockable object — and a gate block is durable + UI-visible rather than a
+ * one-line advisory.
+ *
+ * Pure/structural: this module takes a `GoalServiceLike` seam (the real
+ * `ctx.goals` satisfies it structurally) and an opaque `AgentHandle`, and never
+ * imports the host `@deepseek-ai/dsh-goal` package. The real service's methods
+ * take a live `Agent` and throw if the agent is not the registry's live
+ * instance, so callers pass the live agent from a tool/pre-step `exec`.
+ *
+ * Safety rule: the projection NEVER clobbers a foreign goal. A goal whose
+ * objective is not a `recursive-run:<id>` marker is left untouched (only a
+ * completed goal may be replaced, per the service contract).
+ */
+import type { RunState } from './lifecycle.ts';
+/** Native goal phase (mirrors @deepseek-ai/dsh-goal GoalPhase). */
+export type GoalPhase = 'active' | 'paused' | 'blocked' | 'complete';
+/** CSA identity for one exact goal revision. */
+export interface GoalRefLike {
+    id: string;
+    revision: number;
+}
+/** Input resolved by the service when the round cap is omitted. */
+export interface CreateGoalRequestLike {
+    objective: string;
+    maxGoalRounds?: number;
+}
+/** The subset of the goal view the projection reads. */
+export interface GoalViewLike extends GoalRefLike {
+    objective?: string;
+    phase?: GoalPhase;
+}
+/** Opaque handle to the live DSH Agent; the projection never inspects it further. */
+export interface AgentHandle {
+    session?: {
+        header?: {
+            cwd?: string;
+        };
+    };
+}
+/** Structural seam for the live `goals` service (real methods return GoalView). */
+export interface GoalServiceLike {
+    get(agent: AgentHandle): GoalViewLike | undefined;
+    create(agent: AgentHandle, req: CreateGoalRequestLike): GoalViewLike;
+    block(agent: AgentHandle, ref: GoalRefLike, reason: {
+        code: string;
+        message: string;
+    }): GoalViewLike;
+    pause(agent: AgentHandle, ref: GoalRefLike): GoalViewLike;
+    resume(agent: AgentHandle, ref: GoalRefLike): GoalViewLike;
+    complete(agent: AgentHandle, ref: GoalRefLike): GoalViewLike;
+    clear(agent: AgentHandle, ref: GoalRefLike): GoalRefLike;
+}
+/** Outcome of a run→goal sync. */
+export type SyncResult = {
+    ok: true;
+    phase: GoalPhase;
+    ref?: GoalRefLike;
+    created?: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Marker embedded in the goal objective so a goal can be matched to its run. */
+export declare function runGoalTag(runId: string): string;
+/** The durable objective string for a run goal. */
+export declare function goalObjective(runId: string, runState?: RunState): string;
+/** Map a run state onto the native goal phase it should project to. */
+export declare const RUN_TO_GOAL_PHASE: {
+    readonly new: "active";
+    readonly active: "active";
+    readonly paused: "paused";
+    readonly blocked: "blocked";
+    readonly complete: "complete";
+};
+/** Is this goal's objective the marker for `runId`? */
+export declare function isRunGoal(goal: GoalViewLike | undefined, runId: string): boolean;
+/**
+ * Sync a run's durable goal to the requested phase. Safe: never touches a goal
+ * whose objective is not this run's marker, and never re-creates over a
+ * non-complete foreign goal.
+ */
+export declare function syncRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, runState: RunState): SyncResult;
+/** Block the current run goal (used on a gate-block). Never touches a foreign goal. */
+export declare function blockRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, reason: {
+    code: string;
+    message: string;
+}): SyncResult;
+/** Bridge a run's blocked goal back to active (used on a reopen). */
+export declare function resumeRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string): SyncResult;

package/lib/index.d.ts

@@ -22,6 +22,7 @@ export * from './enforcement.ts';
 export * from './policy.ts';
 export * from './snapshot.ts';
 export * from './live-route.ts';
+export * from './teams-loop.ts';
 /**
  * Bundle plugin entry. The Loader activates this row once `tools` is available
  * (`inject` below); the RecursiveRuntime service is constructed directly so it