@amaster.ai/dsh-a2a 0.1.34 → 0.1.36

package/lib/task-store.js

@@ -85,12 +85,12 @@ export class MemoryTaskStore {
         this.bucket(context).delete(taskId);
     }
 }
+const TERMINAL_REOPEN_GUARD_MS = 24 * 60 * 60 * 1000;
 /** Saves task snapshots on state transitions while keeping active deltas in process. */
 export class SanitizedTaskStore {
     inner;
     lastState = new Map();
     writes = new Map();
-    // Terminal task ids stay guarded until unload, like deleted-id tombstones.
     terminalStates = new Map();
     liveHistory = new Map();
     // ponytail: deleted ids stay tombstoned until plugin unload; use expiring ids if clear volume grows.
@@ -108,6 +108,7 @@ export class SanitizedTaskStore {
             await Promise.all(pending);
         } while ([...this.writes.values()].some((write) => !pending.includes(write)));
         this.liveHistory.clear();
+        this.terminalStates.clear();
         await this.inner.close?.();
     }
     /** Drop SDK saves that may arrive after a clear rejects an in-flight request. */
@@ -121,6 +122,7 @@ export class SanitizedTaskStore {
         await this.inner.delete(taskId, context);
         this.lastState.delete(taskId);
         this.writes.delete(taskId);
+        this.terminalStates.delete(taskId);
     }
     checkpoint(task, context) {
         return this.save(task, context, true);
@@ -129,8 +131,11 @@ export class SanitizedTaskStore {
         if (this.deleted.has(task.id))
             return;
         const state = task.status?.state;
+        const now = Date.now();
         const terminal = this.terminalStates.get(task.id);
-        if (terminal !== undefined && state !== terminal)
+        if (terminal && terminal.expiresAt <= now)
+            this.terminalStates.delete(task.id);
+        else if (terminal && state !== terminal.state)
             return;
         if (state !== undefined &&
             [
@@ -138,8 +143,21 @@ export class SanitizedTaskStore {
                 TaskState.TASK_STATE_CANCELED,
                 TaskState.TASK_STATE_FAILED,
                 TaskState.TASK_STATE_REJECTED,
-            ].includes(state))
-            this.terminalStates.set(task.id, state);
+            ].includes(state)) {
+            // Map order matches expiry order: only the expired prefix needs scanning.
+            for (const [id, guard] of this.terminalStates) {
+                if (guard.expiresAt > now)
+                    break;
+                this.terminalStates.delete(id);
+            }
+            // Re-registering an id refreshes both its deadline and insertion order.
+            this.terminalStates.delete(task.id);
+            this.terminalStates.set(task.id, {
+                state,
+                expiresAt: now + TERMINAL_REOPEN_GUARD_MS,
+            });
+        }
+        // shortcut: WORKING deltas clone and concatenate per event; use chunk accumulators if long streams make this hot path measurable.
         const history = structuredClone(task.history ?? []);
         const current = task.status?.message;
         if (current?.role === Role.ROLE_USER)

package/lib/types/admission.d.ts

@@ -0,0 +1,10 @@
+export type AdmissionRelease = (onCurrent?: () => void) => void;
+export interface Admission {
+    ready: Promise<void>;
+    release: AdmissionRelease;
+}
+/** Small keyed FIFO gate. Cleanup runs only when the releasing tail is still current. */
+export declare class AdmissionGate {
+    private readonly tails;
+    acquire(key: string): Admission;
+}

package/lib/types/bridge.d.ts

@@ -26,6 +26,10 @@ export interface BridgeOptions {
     cwd: string;
     /** Upload root for persisted file parts; absent = the OS temp dir. */
     uploadsDir?: string;
+    /** Allow every private URL host in a trusted intranet. */
+    downloadAllowPrivate?: boolean;
+    /** Private URL file hosts explicitly allowed by the deployment. */
+    downloadAllowedHosts?: readonly string[];
     /** Optional provider/model overrides for created agents. */
     agentOptions?: {
         provider?: string;
@@ -42,6 +46,8 @@ export interface TaskEntry {
     taskId: string;
     sessionId: SessionId;
     handle: AgentHandle;
+    /** An existing native producer retains agent lifecycle ownership. */
+    borrowed?: boolean;
     translator: SessionTranslator;
     /** The in-flight execute()'s bus; null between turns. */
     bus: ExecutionEventBus | null;
@@ -69,6 +75,7 @@ export declare class A2aBridge {
     private readonly bySession;
     private readonly clearing;
     private readonly creating;
+    private readonly admissions;
     private readonly executing;
     private readonly asked;
     private readonly approvals;
@@ -88,6 +95,7 @@ export declare class A2aBridge {
         freshTask: boolean;
     }>;
     private ensureTaskInner;
+    private createAgent;
     /** A2A parts → dsh content blocks; throws only when no part is usable. */
     buildContent(message: Message, contextId: string): Promise<ContentBlock[]>;
     isClearing(contextId: string): boolean;

package/lib/types/content.d.ts

@@ -34,7 +34,13 @@ interface Materialization {
     contextId: string;
     materializer: A2aFileMaterializer;
 }
-export declare function buildMessageContent(parts: readonly Part[], attachments: AttachmentStore | undefined, dir: string, materialization?: Materialization): Promise<ContentBlock[]>;
+export interface UrlDownloadOptions {
+    /** Allow every private/loopback host in a trusted intranet; HTTP(S), size and time limits still apply. */
+    allowPrivate?: boolean;
+    /** Private/loopback hosts are refused unless explicitly named here. */
+    allowedHosts?: readonly string[];
+}
+export declare function buildMessageContent(parts: readonly Part[], attachments: AttachmentStore | undefined, dir: string, materialization?: Materialization, downloads?: UrlDownloadOptions): Promise<ContentBlock[]>;
 /** The directory non-image file parts persist into without a materializer. */
 export declare function uploadsDir(root?: string): string;
 export {};

package/lib/types/executor.d.ts

@@ -22,6 +22,8 @@ import type { A2aBridge } from './bridge.js';
 export declare class DshAgentExecutor implements AgentExecutor {
     private readonly bridge;
     private readonly suppressTask?;
+    private readonly admissions;
+    private readonly admissionFailures;
     constructor(bridge: A2aBridge, suppressTask?: ((taskId: string) => void) | undefined);
     execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void>;
     private executeInner;

package/lib/types/inbox-api.d.ts

@@ -0,0 +1,5 @@
+/** JSON-RPC method extension; standard task methods stay with the official SDK. */
+import { type AgentCard } from '@a2a-js/sdk';
+import type { RequestHandler } from 'express';
+import { type NativeInbox } from './inbox.js';
+export declare function inboxRpcHandler(inbox: NativeInbox, card: AgentCard): RequestHandler;

package/lib/types/inbox-changes.d.ts

@@ -0,0 +1,25 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+export interface InboxChange {
+    contextId: string;
+    version: number;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        'a2a/inbox-checkpointed'(change: InboxChange): void;
+    }
+}
+/** Invalidation only: DSH owns the queue, sequence and durability barrier. */
+export declare class InboxChanges {
+    private readonly ctx;
+    private readonly states;
+    private readonly listeners;
+    private readonly disposed;
+    private readonly detach;
+    private stopped;
+    constructor(ctx: Context, managed: (contextId: string) => boolean, enabled?: boolean);
+    watch(session: Session, listener: (change: InboxChange) => void, closed: () => void): () => void;
+    checkpoint(session: Session): Promise<InboxChange>;
+    close(): void;
+    private closeSession;
+}

package/lib/types/inbox.d.ts

@@ -6,10 +6,11 @@ import type { GoalMessageSource } from '@deepseek-ai/dsh-goal';
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types';
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
 import type { A2aBridge } from './bridge.js';
+import { InboxChanges } from './inbox-changes.js';
 import type { A2aTurnContext } from './index.js';
 import type { A2aServer } from './server.js';
 import { type ManagedTaskStore } from './task-store.js';
-export declare const INBOX_EXTENSION = "https://github.com/TGYD-helige/dsh-plugins/blob/main/docs/protocol/inbox-v1.md";
+export declare const INBOX_EXTENSION = "https://github.com/TGYD-helige/dsh-plugins/blob/main/packages/dsh-a2a/README.md";
 export interface A2aInboxEvent {
     phase: string;
     contextId: string;
@@ -45,6 +46,13 @@ declare module '@deepseek-ai/dsh-llm/types' {
         goal: GoalMessageSource;
     }
 }
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        'agent/inbox/paused': {
+            paused: boolean;
+        };
+    }
+}
 declare module '@deepseek-ai/cordis' {
     interface Events {
         /** Native inbox lifecycle; content consumers must honor their capture settings. */
@@ -55,6 +63,12 @@ declare module '@deepseek-ai/cordis' {
 }
 /** Same-process queue control; wire messages and task subscriptions remain standard A2A. */
 export interface A2aInbox {
+    get(contextId: string, page?: InboxPageOptions): Promise<InboxSnapshot>;
+    update(contextId: string, id: string, message: Message, page?: InboxPageOptions): Promise<InboxSnapshot>;
+    move(contextId: string, id: string, index: number, page?: InboxPageOptions): Promise<InboxSnapshot>;
+    remove(contextId: string, id: string, page?: InboxPageOptions): Promise<InboxSnapshot>;
+    clearPending(contextId: string, page?: InboxPageOptions): Promise<InboxSnapshot>;
+    executePending(contextId: string, id?: string, page?: InboxPageOptions): Promise<InboxSnapshot>;
     resolve(contextId: string): Promise<Agent>;
     content(message: Message, contextId: string): Promise<ContentBlock[]>;
     /** Admit a same-process host follow-up under an existing task's durable identity. */
@@ -64,14 +78,42 @@ export interface A2aInbox {
     }): Promise<void>;
     /** Transfer one unclaimed independent input into the active task. */
     promote(contextId: string, messageId: string, taskId: string): Promise<void>;
+    /** Explicitly resume terminal retained input under a fresh task identity. */
+    resume(contextId: string, taskId: string): Promise<string>;
+    /** Pause admission and the current driver while retaining pending input. */
+    pause(contextId: string): Promise<void>;
+    /** Wake retained work in queue order without creating a replacement task. */
+    wake(contextId: string): Promise<string[]>;
     /** Standard cancellation is terminal and removes only this task's pending input. */
     cancel(taskId: string): Promise<string | undefined>;
 }
+export interface InboxSnapshot {
+    contextId: string;
+    version: number;
+    nextTurn: Array<{
+        id: string;
+        message: unknown;
+        editable: boolean;
+    }>;
+    nextStep: Array<{
+        id: string;
+        message: unknown;
+        editable: boolean;
+    }>;
+    totalSize: number;
+    nextPageToken: string;
+}
+export interface InboxPageOptions {
+    pageSize?: number;
+    pageToken?: string;
+}
+export declare function validateInboxPage(page?: InboxPageOptions): void;
 export declare class NativeInbox implements A2aInbox {
     private readonly ctx;
     private readonly bridge;
     private readonly store;
     private readonly retainPending;
+    readonly changes: InboxChanges;
     private readonly contexts;
     private readonly resolving;
     private stopping;
@@ -79,10 +121,20 @@ export declare class NativeInbox implements A2aInbox {
     private readonly preadmitted;
     server?: A2aServer;
     private readonly persistence?;
-    constructor(ctx: Context, bridge: A2aBridge, store: ManagedTaskStore, retainPending?: boolean);
+    constructor(ctx: Context, bridge: A2aBridge, store: ManagedTaskStore, retainPending?: boolean, notifications?: boolean);
     private unloading;
     content(message: Message, contextId: string): Promise<ContentBlock[]>;
     resolve(contextId: string): Promise<Agent>;
+    get(contextId: string, page?: InboxPageOptions): Promise<InboxSnapshot>;
+    private editQueue;
+    private queued;
+    update(contextId: string, id: string, message: Message, page?: InboxPageOptions): Promise<InboxSnapshot>;
+    move(contextId: string, id: string, index: number, page?: InboxPageOptions): Promise<InboxSnapshot>;
+    private reorder;
+    private removed;
+    remove(contextId: string, id: string, page?: InboxPageOptions): Promise<InboxSnapshot>;
+    clearPending(contextId: string, page?: InboxPageOptions): Promise<InboxSnapshot>;
+    executePending(contextId: string, id?: string, page?: InboxPageOptions): Promise<InboxSnapshot>;
     enqueue(taskId: string, message: Message, options?: {
         target?: InboxTarget;
         wakeup?: boolean;
@@ -90,6 +142,7 @@ export declare class NativeInbox implements A2aInbox {
     private moveInput;
     promote(contextId: string, messageId: string, taskId: string): Promise<void>;
     private promoteInput;
+    resume(contextId: string, taskId: string): Promise<string>;
     /** Repair only an incomplete ownership move, never an ordinary DSH claim. */
     private recoverPromotions;
     private recoverRetained;
@@ -122,6 +175,9 @@ export declare class NativeInbox implements A2aInbox {
     private discard;
     cancel(taskId: string): Promise<string | undefined>;
     private cancelTask;
+    private requeueClaimed;
+    pause(contextId: string): Promise<void>;
+    wake(contextId: string): Promise<string[]>;
     clear(contextId: string): Promise<void>;
     onDisposed(session: Session): void;
     shutdown(): Promise<void>;