@tangle-network/agent-runtime 0.4.2 → 0.5.0

package/README.md

@@ -2,10 +2,10 @@
 
 Reusable runtime lifecycle for domain-specific agents.
 
-`agent-runtime` is the shared skeleton for tax, legal, GTM, creative,
-agent-builder generated agents, blueprint-agent, redteam, and similar packages.
-It does not own domain policy, tools, connectors, or UI. It standardizes the
-task lifecycle and delegates domain behavior to an adapter.
+`agent-runtime` is the shared skeleton for domain agents, generated agents,
+red-team harnesses, coding agents, and similar packages. It does not own domain
+policy, tools, connectors, model routing, or UI. It standardizes the task
+lifecycle and delegates domain behavior to an adapter.
 
 ```txt
 TaskSpec
@@ -16,6 +16,16 @@ TaskSpec
   -> Run evidence
 ```
 
+For product agents that already have a streaming backend, use the stream kernel:
+
+```txt
+TaskSpec
+  -> Knowledge readiness
+  -> Session create/resume
+  -> Backend stream
+  -> Sanitized RuntimeStreamEvent/SSE
+```
+
 ## Install
 
 ```bash
@@ -72,6 +82,63 @@ Events cover readiness, question answering, acquisition, control-loop steps,
 and task completion. This keeps streaming UI, logs, and telemetry out of domain
 adapters while making every runtime transition observable.
 
+This package does not stream model tokens for you. Domain adapters and product
+routes still own model calls, tool execution, and token streaming. `agent-runtime`
+emits lifecycle events around those actions, and provides small helpers for
+safe telemetry streams:
+
+```ts
+import { readinessServerSentEvent } from '@tangle-network/agent-runtime'
+
+writer.write(encoder.encode(readinessServerSentEvent(readinessReport)))
+```
+
+Use these helpers when an app wants to expose readiness or runtime metadata over
+Server-Sent Events without leaking raw task inputs, credentials, or evidence.
+
+For main product loops, prefer `runAgentTaskStream` with an execution backend:
+
+```ts
+import {
+  InMemoryRuntimeSessionStore,
+  createSandboxPromptBackend,
+  runAgentTaskStream,
+  runtimeStreamServerSentEvent,
+} from '@tangle-network/agent-runtime'
+
+const backend = createSandboxPromptBackend({
+  getBox: () => sandboxClient.get(sandboxId),
+  streamPrompt: (box, message) => box.streamPrompt(message),
+  getSessionId: (box) => box.id,
+})
+
+const sessions = new InMemoryRuntimeSessionStore()
+
+for await (const event of runAgentTaskStream({
+  task,
+  backend,
+  input: { message },
+  sessionId,
+  resume: Boolean(sessionId),
+  sessionStore: sessions,
+})) {
+  writer.write(encoder.encode(runtimeStreamServerSentEvent(event)))
+}
+```
+
+`runAgentTaskStream` is the product-facing kernel. It readiness-gates execution,
+creates or resumes a backend session, normalizes text/tool/artifact/error/final
+events, and lets callers persist resumable session history. The package ships
+SDK-agnostic adapter factories for:
+
+- `createOpenAICompatibleBackend` for TCloud/OpenAI-compatible chat APIs.
+- `createCliBridgeBackend` for HTTP CLI bridge streams.
+- `createSandboxPromptBackend` for sandbox/sidecar `streamPrompt` clients.
+- `createIterableBackend` for custom coding harnesses or browser agents.
+
+The adapters are intentionally thin. Product repos still own client
+construction, auth, concrete tool permissions, and UI behavior.
+
 For logs, reports, and UI telemetry, do not serialize raw events directly.
 Use the built-in sanitized collector:
 

package/dist/index.d.ts

@@ -126,6 +126,176 @@ type AgentRuntimeEvent<TState = unknown, TAction = unknown, TActionResult = unkn
     reason: string;
 };
 type AgentRuntimeEventSink<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult> = (event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>) => Promise<void> | void;
+type RuntimeStreamEvent = {
+    type: 'task_start';
+    task: AgentTaskSpec;
+    timestamp: string;
+} | {
+    type: 'readiness_start';
+    task: AgentTaskSpec;
+    timestamp: string;
+} | {
+    type: 'readiness_end';
+    task: AgentTaskSpec;
+    knowledge: KnowledgeReadinessReport;
+    decision: KnowledgeReadinessDecision;
+    timestamp: string;
+} | {
+    type: 'questions_start';
+    task: AgentTaskSpec;
+    questions: UserQuestion[];
+    timestamp: string;
+} | {
+    type: 'questions_end';
+    task: AgentTaskSpec;
+    questions: UserQuestion[];
+    userAnswers: Record<string, string>;
+    timestamp: string;
+} | {
+    type: 'acquisition_start';
+    task: AgentTaskSpec;
+    acquisitionPlans: DataAcquisitionPlan[];
+    timestamp: string;
+} | {
+    type: 'acquisition_end';
+    task: AgentTaskSpec;
+    acquisitionPlans: DataAcquisitionPlan[];
+    acquiredEvidenceIds: string[];
+    timestamp: string;
+} | {
+    type: 'session_created';
+    task: AgentTaskSpec;
+    session: RuntimeSession;
+    timestamp: string;
+} | {
+    type: 'session_resumed';
+    task: AgentTaskSpec;
+    session: RuntimeSession;
+    timestamp: string;
+} | {
+    type: 'backend_start';
+    task: AgentTaskSpec;
+    session: RuntimeSession;
+    backend: string;
+    timestamp: string;
+} | {
+    type: 'text_delta';
+    task?: AgentTaskSpec;
+    session?: RuntimeSession;
+    text: string;
+    timestamp?: string;
+} | {
+    type: 'reasoning_delta';
+    task?: AgentTaskSpec;
+    session?: RuntimeSession;
+    text: string;
+    timestamp?: string;
+} | {
+    type: 'tool_call';
+    task?: AgentTaskSpec;
+    session?: RuntimeSession;
+    toolName: string;
+    toolCallId?: string;
+    args?: unknown;
+    timestamp?: string;
+} | {
+    type: 'tool_result';
+    task?: AgentTaskSpec;
+    session?: RuntimeSession;
+    toolName: string;
+    toolCallId?: string;
+    result?: unknown;
+    timestamp?: string;
+} | {
+    type: 'artifact';
+    task?: AgentTaskSpec;
+    session?: RuntimeSession;
+    artifactId: string;
+    name?: string;
+    mimeType?: string;
+    uri?: string;
+    metadata?: Record<string, unknown>;
+    timestamp?: string;
+} | {
+    type: 'backend_error';
+    task: AgentTaskSpec;
+    session?: RuntimeSession;
+    backend: string;
+    message: string;
+    recoverable: boolean;
+    timestamp: string;
+} | {
+    type: 'backend_end';
+    task: AgentTaskSpec;
+    session: RuntimeSession;
+    backend: string;
+    timestamp: string;
+} | {
+    type: 'task_end';
+    task: AgentTaskSpec;
+    status: AgentTaskStatus;
+    reason: string;
+    timestamp: string;
+} | {
+    type: 'final';
+    task: AgentTaskSpec;
+    session?: RuntimeSession;
+    status: AgentTaskStatus;
+    reason: string;
+    text?: string;
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+};
+interface RuntimeSession {
+    id: string;
+    backend: string;
+    status: 'active' | 'completed' | 'failed' | 'aborted';
+    resumeToken?: string;
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Record<string, unknown>;
+}
+interface RuntimeSessionStore {
+    get(sessionId: string): Promise<RuntimeSession | undefined> | RuntimeSession | undefined;
+    put(session: RuntimeSession): Promise<void> | void;
+    appendEvent?(sessionId: string, event: RuntimeStreamEvent): Promise<void> | void;
+    listEvents?(sessionId: string): Promise<RuntimeStreamEvent[]> | RuntimeStreamEvent[];
+}
+interface AgentBackendInput {
+    task: AgentTaskSpec;
+    message?: string;
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
+    inputs?: Record<string, unknown>;
+}
+interface AgentBackendContext {
+    task: AgentTaskSpec;
+    knowledge: KnowledgeReadinessReport;
+    session: RuntimeSession;
+    signal?: AbortSignal;
+}
+interface AgentExecutionBackend<TInput extends AgentBackendInput = AgentBackendInput> {
+    kind: string;
+    start?(input: TInput, context: Omit<AgentBackendContext, 'session'> & {
+        requestedSessionId?: string;
+    }): Promise<RuntimeSession> | RuntimeSession;
+    resume?(session: RuntimeSession, input: TInput, context: Omit<AgentBackendContext, 'session'>): Promise<RuntimeSession> | RuntimeSession;
+    stream(input: TInput, context: AgentBackendContext): AsyncIterable<RuntimeStreamEvent>;
+    stop?(session: RuntimeSession, reason: string): Promise<void> | void;
+}
+interface RunAgentTaskStreamOptions<TInput extends AgentBackendInput = AgentBackendInput> {
+    task: AgentTaskSpec;
+    backend: AgentExecutionBackend<TInput>;
+    input?: Omit<TInput, 'task'>;
+    knowledge?: AgentKnowledgeProvider;
+    sessionStore?: RuntimeSessionStore;
+    sessionId?: string;
+    resume?: boolean;
+    signal?: AbortSignal;
+    minimumReadinessScore?: number;
+}
 interface RunAgentTaskOptions<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
     task: AgentTaskSpec;
     adapter: AgentAdapter<TState, TAction, TActionResult, TEval>;
@@ -233,15 +403,53 @@ interface ServerSentEventOptions {
     id?: string;
     retry?: number;
 }
+declare class InMemoryRuntimeSessionStore implements RuntimeSessionStore {
+    private readonly sessions;
+    private readonly events;
+    get(sessionId: string): RuntimeSession | undefined;
+    put(session: RuntimeSession): void;
+    appendEvent(sessionId: string, event: RuntimeStreamEvent): void;
+    listEvents(sessionId: string): RuntimeStreamEvent[];
+}
 declare function runAgentTask<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult>(options: RunAgentTaskOptions<TState, TAction, TActionResult, TEval>): Promise<AgentTaskRunResult<TState, TAction, TActionResult, TEval>>;
 declare function summarizeAgentTaskRun<TState, TAction, TActionResult, TEval extends ControlEvalResult>(result: AgentTaskRunResult<TState, TAction, TActionResult, TEval>): AgentTaskRunSummary;
+declare function runAgentTaskStream<TInput extends AgentBackendInput = AgentBackendInput>(options: RunAgentTaskStreamOptions<TInput>): AsyncIterable<RuntimeStreamEvent>;
 declare function decideKnowledgeReadiness(report: KnowledgeReadinessReport, options?: {
     minimumScore?: number;
 }): KnowledgeReadinessDecision;
 declare function sanitizeKnowledgeReadinessReport(report: KnowledgeReadinessReport, options?: RuntimeTelemetryOptions): SanitizedKnowledgeReadinessReport;
 declare function sanitizeAgentRuntimeEvent<TState, TAction, TActionResult, TEval extends ControlEvalResult>(event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>, options?: RuntimeTelemetryOptions): Record<string, unknown>;
+declare function sanitizeRuntimeStreamEvent(event: RuntimeStreamEvent, options?: RuntimeTelemetryOptions): Record<string, unknown>;
 declare function createRuntimeEventCollector<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult>(options?: RuntimeTelemetryOptions): RuntimeEventCollector<TState, TAction, TActionResult, TEval>;
 declare function encodeServerSentEvent(data: unknown, options?: ServerSentEventOptions): string;
 declare function readinessServerSentEvent(report: KnowledgeReadinessReport, options?: RuntimeTelemetryOptions & ServerSentEventOptions): string;
+declare function runtimeStreamServerSentEvent(event: RuntimeStreamEvent, options?: RuntimeTelemetryOptions & ServerSentEventOptions): string;
+declare function createIterableBackend<TInput extends AgentBackendInput>(options: {
+    kind: string;
+    start?: AgentExecutionBackend<TInput>['start'];
+    resume?: AgentExecutionBackend<TInput>['resume'];
+    stream: AgentExecutionBackend<TInput>['stream'];
+    stop?: AgentExecutionBackend<TInput>['stop'];
+}): AgentExecutionBackend<TInput>;
+declare function createSandboxPromptBackend<TBox, TInput extends AgentBackendInput = AgentBackendInput>(options: {
+    kind?: string;
+    getBox(input: TInput, context: Omit<AgentBackendContext, 'session'>): Promise<TBox> | TBox;
+    streamPrompt(box: TBox, message: string, context: AgentBackendContext): AsyncIterable<unknown>;
+    mapEvent?: (event: unknown, context: AgentBackendContext) => RuntimeStreamEvent | undefined;
+    getSessionId?: (box: TBox, input: TInput) => string | undefined;
+}): AgentExecutionBackend<TInput>;
+declare function createCliBridgeBackend<TInput extends AgentBackendInput = AgentBackendInput>(options: {
+    url: string;
+    bearer?: string;
+    kind?: string;
+    fetchImpl?: typeof fetch;
+}): AgentExecutionBackend<TInput>;
+declare function createOpenAICompatibleBackend<TInput extends AgentBackendInput = AgentBackendInput>(options: {
+    apiKey: string;
+    baseUrl: string;
+    model: string;
+    kind?: string;
+    fetchImpl?: typeof fetch;
+}): AgentExecutionBackend<TInput>;
 
-export { type AgentAdapter, type AgentKnowledgeProvider, type AgentRuntimeEvent, type AgentRuntimeEventSink, type AgentTaskContext, type AgentTaskRunResult, type AgentTaskRunSummary, type AgentTaskSpec, type AgentTaskStatus, type KnowledgeReadinessDecision, type RunAgentTaskOptions, type RuntimeEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SanitizedKnowledgeRequirement, type ServerSentEventOptions, createRuntimeEventCollector, decideKnowledgeReadiness, encodeServerSentEvent, readinessServerSentEvent, runAgentTask, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, summarizeAgentTaskRun };
+export { type AgentAdapter, type AgentBackendContext, type AgentBackendInput, type AgentExecutionBackend, type AgentKnowledgeProvider, type AgentRuntimeEvent, type AgentRuntimeEventSink, type AgentTaskContext, type AgentTaskRunResult, type AgentTaskRunSummary, type AgentTaskSpec, type AgentTaskStatus, InMemoryRuntimeSessionStore, type KnowledgeReadinessDecision, type RunAgentTaskOptions, type RunAgentTaskStreamOptions, type RuntimeEventCollector, type RuntimeSession, type RuntimeSessionStore, type RuntimeStreamEvent, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SanitizedKnowledgeRequirement, type ServerSentEventOptions, createCliBridgeBackend, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createSandboxPromptBackend, decideKnowledgeReadiness, encodeServerSentEvent, readinessServerSentEvent, runAgentTask, runAgentTaskStream, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, summarizeAgentTaskRun };