@peer-agent/runtime-sdk 0.0.1-beta.43

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 梁音
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @peer-agent/runtime-sdk
+
+Public host-neutral orchestration SDK for embedding Peer Agent Runtime in a custom Node host.
+
+## Install
+
+```bash
+npm install @peer-agent/runtime-sdk
+```
+
+The SDK depends on the matching public `@peer-agent/protocol` and `@peer-agent/runtime-core` versions.
+
+## Main APIs
+
+```js
+import {
+  createRuntimeSdk,
+  createRuntimeSessionController,
+  createRuntimePipeline,
+} from '@peer-agent/runtime-sdk';
+```
+
+| API | Purpose |
+|-----|---------|
+| `createRuntimeSdk` | execute governed tool calls through a host port; emit runtime lifecycle events |
+| `createRuntimeSessionController` | own session / turn / cancel / complete / fail state |
+| `createRuntimePipeline` | sequence model turns, projected tool execution, and tool-result feedback |
+
+## Host boundary
+
+Your host implements environment-specific ports (provider execution, authorization/blocking, optional hooks, model adapter and tool executor). The SDK does not require:
+
+- Desktop / Electron
+- `@peer-agent/cli` or the `peer` binary
+- TUI / OpenTUI
+- `@peer-agent/runtime-node`
+
+A runnable external-host example lives at [`examples/external-host`](../../examples/external-host).
+
+## Product vs SDK
+
+| Need | Install |
+|------|---------|
+| Run terminal product | `npm i -g @peer-agent/cli` |
+| Embed runtime | `npm i @peer-agent/runtime-sdk` |
+| Desktop GUI | Desktop release |
+
+These are parallel product surfaces, not dependency chains.
+
+## Version policy
+
+During beta, protocol / runtime-core / runtime-sdk follow the repository root `VERSION` and publish with the same npm dist-tag as CLI/Desktop releases.

package/dist/contracts.d.ts

@@ -0,0 +1,168 @@
+import type { RuntimeDecision } from '@peer-agent/runtime-core';
+import type { ContextAccountingSnapshot, RuntimeExecuteRequest, RuntimeExecutionContext, RuntimeToolCall, RuntimeToolResult } from '@peer-agent/protocol';
+export type { RuntimeExecuteRequest, RuntimeExecutionContext, RuntimeToolCall, RuntimeToolResult, } from '@peer-agent/protocol';
+export declare const RUNTIME_EVENT_PROTOCOL_VERSION: 1;
+export type RuntimeEventProtocolVersion = typeof RUNTIME_EVENT_PROTOCOL_VERSION;
+export type RuntimeSdkEventType = 'session.started' | 'message.delta' | 'reasoning.delta' | 'message.completed' | 'runtime.error' | 'tool.started' | 'hook.completed' | 'permission.requested' | 'permission.resolved' | 'tool.completed' | 'compaction.progress' | 'context.accounting';
+export type RuntimeSdkToolCall = RuntimeToolCall;
+export type RuntimeSdkExecuteRequest = RuntimeExecuteRequest;
+export type RuntimeSdkExecutionContext = RuntimeExecutionContext;
+export type RuntimeSdkToolResult = RuntimeToolResult;
+export interface RuntimeSdkProviderExecution {
+    readonly result: RuntimeSdkToolResult;
+    readonly [key: string]: unknown;
+}
+export interface RuntimeSdkHookRecord {
+    readonly hookId?: string;
+    readonly decision?: RuntimeDecision;
+    readonly reason?: string;
+    readonly [key: string]: unknown;
+}
+export interface RuntimeSdkHookPayload {
+    readonly sessionId?: string;
+    readonly projectionId?: string;
+    readonly conversationId?: string;
+    readonly call: RuntimeSdkToolCall;
+    readonly result?: RuntimeSdkToolResult;
+}
+export interface RuntimeSdkHookRunner {
+    runPreToolUse?(payload: RuntimeSdkHookPayload): Promise<readonly RuntimeSdkHookRecord[]> | readonly RuntimeSdkHookRecord[];
+    runPostToolUse?(payload: RuntimeSdkHookPayload): Promise<readonly RuntimeSdkHookRecord[]> | readonly RuntimeSdkHookRecord[];
+}
+export interface RuntimeSdkPermissionRequest {
+    readonly kind: 'hook';
+    readonly hookEvent: 'PreToolUse';
+    readonly call: RuntimeSdkToolCall;
+    readonly toolCallId: string;
+    readonly capabilityId: string;
+    readonly args: unknown;
+    readonly workspacePath?: string;
+    readonly reason: string;
+}
+export interface RuntimeSdkApprovalDecision {
+    readonly decision: RuntimeDecision;
+    readonly [key: string]: unknown;
+}
+export interface RuntimeSdkApprovalPort {
+    requestApproval(request: RuntimeSdkPermissionRequest, context: RuntimeSdkExecutionContext): Promise<RuntimeSdkApprovalDecision> | RuntimeSdkApprovalDecision;
+}
+export interface RuntimeSdkHostAdapter {
+    executeProvider(request: RuntimeSdkExecuteRequest, context: RuntimeSdkExecutionContext): Promise<RuntimeSdkProviderExecution> | RuntimeSdkProviderExecution;
+    createBlockedExecution(options: {
+        readonly request: RuntimeSdkExecuteRequest;
+        readonly context: RuntimeSdkExecutionContext;
+        readonly decision: RuntimeDecision;
+        readonly reason: string;
+        readonly approval?: RuntimeSdkApprovalDecision;
+    }): RuntimeSdkProviderExecution;
+    appendHookEvidence?(result: RuntimeSdkToolResult, records: readonly RuntimeSdkHookRecord[], finalDecision: RuntimeDecision): RuntimeSdkToolResult;
+    hookRunner?: RuntimeSdkHookRunner | null;
+    approvalPort?: RuntimeSdkApprovalPort | null;
+}
+export interface RuntimeSdkEventBase {
+    readonly protocolVersion: RuntimeEventProtocolVersion;
+    readonly eventId: string;
+    readonly sequence: number;
+    readonly occurredAt: string;
+    readonly sessionId?: string;
+    readonly streamId?: string;
+    readonly projectionId?: string;
+    readonly conversationId?: string;
+    readonly toolCallId?: string;
+    readonly capabilityId?: string;
+}
+export interface RuntimeSdkSessionStartedEvent extends RuntimeSdkEventBase {
+    readonly type: 'session.started';
+    readonly sessionId: string;
+    readonly streamId?: string;
+    readonly mode?: string;
+    readonly providerId?: string;
+    readonly model?: string;
+}
+export interface RuntimeSdkMessageDeltaEvent extends RuntimeSdkEventBase {
+    readonly type: 'message.delta';
+    readonly streamId: string;
+    readonly content: string;
+}
+export interface RuntimeSdkReasoningDeltaEvent extends RuntimeSdkEventBase {
+    readonly type: 'reasoning.delta';
+    readonly streamId: string;
+    readonly content: string;
+}
+/**
+ * Mid-turn / automatic compaction progress for host UI surfaces.
+ * percent is 0-100; hosts should treat values below 100 as live progress.
+ */
+export interface RuntimeSdkCompactionProgressEvent extends RuntimeSdkEventBase {
+    readonly type: 'compaction.progress';
+    readonly streamId: string;
+    readonly percent: number;
+    readonly reason?: 'preflight' | 'overflow' | 'manual' | string;
+    readonly phase?: 'started' | 'progress' | 'done';
+    readonly label?: string;
+}
+/** Shared Desktop/TUI context-capacity state. Presentation consumes this verbatim. */
+export interface RuntimeSdkContextAccountingEvent extends RuntimeSdkEventBase {
+    readonly type: 'context.accounting';
+    readonly snapshot: ContextAccountingSnapshot;
+}
+export interface RuntimeSdkMessageCompletedEvent extends RuntimeSdkEventBase {
+    readonly type: 'message.completed';
+    readonly streamId: string;
+    readonly content?: string;
+    readonly usage?: unknown;
+    readonly lifetimeUsage?: unknown;
+    readonly finishReason?: string;
+}
+export interface RuntimeSdkRuntimeErrorEvent extends RuntimeSdkEventBase {
+    readonly type: 'runtime.error';
+    readonly code: string;
+    readonly message?: string;
+    readonly recoverable?: boolean;
+    readonly details?: unknown;
+}
+export interface RuntimeSdkToolStartedEvent extends RuntimeSdkEventBase {
+    readonly toolCallId: string;
+    readonly capabilityId: string;
+    readonly type: 'tool.started';
+}
+export interface RuntimeSdkHookCompletedEvent extends RuntimeSdkEventBase {
+    readonly toolCallId: string;
+    readonly capabilityId: string;
+    readonly type: 'hook.completed';
+    readonly phase: 'PreToolUse' | 'PostToolUse';
+    readonly decision: RuntimeDecision;
+    readonly records: readonly RuntimeSdkHookRecord[];
+}
+export interface RuntimeSdkPermissionRequestedEvent extends RuntimeSdkEventBase {
+    readonly toolCallId: string;
+    readonly capabilityId: string;
+    readonly type: 'permission.requested';
+    readonly decision: 'ask';
+}
+export interface RuntimeSdkPermissionResolvedEvent extends RuntimeSdkEventBase {
+    readonly toolCallId: string;
+    readonly capabilityId: string;
+    readonly type: 'permission.resolved';
+    readonly decision: RuntimeDecision;
+}
+export interface RuntimeSdkToolCompletedEvent extends RuntimeSdkEventBase {
+    readonly toolCallId: string;
+    readonly capabilityId: string;
+    readonly type: 'tool.completed';
+    readonly decision: RuntimeDecision;
+    readonly result: RuntimeSdkToolResult;
+}
+export type RuntimeSdkEvent = RuntimeSdkSessionStartedEvent | RuntimeSdkMessageDeltaEvent | RuntimeSdkReasoningDeltaEvent | RuntimeSdkCompactionProgressEvent | RuntimeSdkContextAccountingEvent | RuntimeSdkMessageCompletedEvent | RuntimeSdkRuntimeErrorEvent | RuntimeSdkToolStartedEvent | RuntimeSdkHookCompletedEvent | RuntimeSdkPermissionRequestedEvent | RuntimeSdkPermissionResolvedEvent | RuntimeSdkToolCompletedEvent;
+export type RuntimeSdkEventInput = RuntimeSdkEvent extends infer Event ? Event extends RuntimeSdkEvent ? Omit<Event, 'protocolVersion' | 'eventId' | 'sequence' | 'occurredAt'> : never : never;
+export type RuntimeSdkEventListener = (event: RuntimeSdkEvent) => void;
+export interface RuntimeSdkOptions {
+    readonly host: RuntimeSdkHostAdapter;
+    readonly workspaceRoot?: string;
+    readonly now?: () => string;
+}
+export interface RuntimeSdk {
+    execute(request: RuntimeSdkExecuteRequest, context?: RuntimeSdkExecutionContext): Promise<RuntimeSdkProviderExecution>;
+    emit(event: RuntimeSdkEventInput): RuntimeSdkEvent;
+    subscribe(listener: RuntimeSdkEventListener): () => void;
+}

package/dist/contracts.js

@@ -0,0 +1 @@
+export const RUNTIME_EVENT_PROTOCOL_VERSION = 1;

package/dist/goal-contracts.d.ts

@@ -0,0 +1,73 @@
+export type RuntimeGoalStatus = 'pending' | 'running' | 'paused' | 'blocked' | 'completed' | 'failed' | 'cancelled';
+export type RuntimeGoalTaskStatus = 'pending' | 'running' | 'completed' | 'blocked' | 'failed' | 'cancelled';
+export interface RuntimeGoalTaskInput {
+    readonly taskId: string;
+    readonly title: string;
+}
+export interface RuntimeGoalSuccessCriterion {
+    readonly description: string;
+}
+export interface RuntimeGoalTaskSnapshot extends RuntimeGoalTaskInput {
+    readonly status: RuntimeGoalTaskStatus;
+    readonly startedAt?: string;
+    readonly completedAt?: string;
+    readonly reason?: string;
+    readonly evidenceRefs: readonly string[];
+}
+export interface RuntimeGoalSnapshot {
+    readonly goalId: string;
+    readonly sourcePlanId: string;
+    readonly sessionId: string;
+    readonly title: string;
+    readonly goal: string;
+    readonly status: RuntimeGoalStatus;
+    readonly tasks: readonly RuntimeGoalTaskSnapshot[];
+    readonly successCriteria: readonly RuntimeGoalSuccessCriterion[];
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly reason?: string;
+}
+export interface RuntimeGoalCreateOptions {
+    readonly goalId: string;
+    readonly sourcePlanId: string;
+    readonly sessionId: string;
+    readonly title: string;
+    readonly goal: string;
+    readonly tasks: readonly RuntimeGoalTaskInput[];
+    readonly successCriteria?: readonly RuntimeGoalSuccessCriterion[];
+}
+export type RuntimeGoalTaskExecutionResult = {
+    readonly status: 'completed';
+    readonly evidenceRefs: readonly string[];
+} | {
+    readonly status: 'blocked';
+    readonly reason: string;
+    readonly evidenceRefs?: readonly string[];
+} | {
+    readonly status: 'failed';
+    readonly reason: string;
+    readonly evidenceRefs?: readonly string[];
+};
+export interface RuntimeGoalTaskExecutionContext {
+    readonly goalId: string;
+    readonly sourcePlanId: string;
+    readonly sessionId: string;
+    readonly taskIndex: number;
+    readonly signal: AbortSignal;
+}
+export type RuntimeGoalTaskExecutor = (task: RuntimeGoalTaskInput, context: RuntimeGoalTaskExecutionContext) => Promise<RuntimeGoalTaskExecutionResult>;
+export interface RuntimeGoalControllerOptions {
+    readonly executeTask: RuntimeGoalTaskExecutor;
+    readonly now?: () => string;
+    readonly onChange?: (snapshot: RuntimeGoalSnapshot) => void;
+}
+export interface RuntimeGoalController {
+    create(options: RuntimeGoalCreateOptions): RuntimeGoalSnapshot;
+    start(goalId: string): Promise<RuntimeGoalSnapshot>;
+    pause(goalId: string): RuntimeGoalSnapshot;
+    resume(goalId: string): Promise<RuntimeGoalSnapshot>;
+    cancel(goalId: string, reason?: string): RuntimeGoalSnapshot;
+    get(goalId: string): RuntimeGoalSnapshot | null;
+    list(): readonly RuntimeGoalSnapshot[];
+    subscribe(listener: (snapshot: RuntimeGoalSnapshot) => void): () => void;
+}

package/dist/goal-contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/goal-controller.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeGoalController, RuntimeGoalControllerOptions } from './goal-contracts.ts';
+export declare function createRuntimeGoalController(options: RuntimeGoalControllerOptions): RuntimeGoalController;

package/dist/goal-controller.js

@@ -0,0 +1,191 @@
+export function createRuntimeGoalController(options) {
+    const now = options.now ?? (() => new Date().toISOString());
+    const goals = new Map();
+    const planGoals = new Map();
+    const listeners = new Set();
+    const publish = (record, snapshot) => {
+        record.snapshot = snapshot;
+        options.onChange?.(snapshot);
+        for (const listener of listeners)
+            listener(snapshot);
+        return snapshot;
+    };
+    const update = (record, change) => publish(record, {
+        ...record.snapshot,
+        ...change,
+        updatedAt: now(),
+    });
+    const requireGoal = (goalId) => {
+        const record = goals.get(goalId);
+        if (!record)
+            throw new Error(`Runtime goal ${goalId} does not exist.`);
+        return record;
+    };
+    const run = async (record) => {
+        if (record.run)
+            return record.run;
+        record.pauseRequested = false;
+        const controller = new AbortController();
+        record.controller = controller;
+        update(record, { status: 'running', reason: undefined });
+        const promise = (async () => {
+            try {
+                while (!controller.signal.aborted) {
+                    if (record.pauseRequested)
+                        return update(record, { status: 'paused' });
+                    const taskIndex = record.snapshot.tasks.findIndex((task) => task.status === 'pending');
+                    if (taskIndex < 0)
+                        return update(record, { status: 'completed' });
+                    const startedAt = now();
+                    const runningTask = {
+                        ...record.snapshot.tasks[taskIndex],
+                        status: 'running',
+                        startedAt,
+                    };
+                    const runningTasks = [...record.snapshot.tasks];
+                    runningTasks[taskIndex] = runningTask;
+                    update(record, { tasks: runningTasks });
+                    const result = await options.executeTask(runningTask, {
+                        goalId: record.snapshot.goalId,
+                        sourcePlanId: record.snapshot.sourcePlanId,
+                        sessionId: record.snapshot.sessionId,
+                        taskIndex,
+                        signal: controller.signal,
+                    });
+                    if (controller.signal.aborted) {
+                        const cancelledTasks = record.snapshot.tasks.map((task, index) => index === taskIndex
+                            ? { ...task, status: 'cancelled', completedAt: now(), reason: String(controller.signal.reason ?? 'cancelled') }
+                            : task);
+                        return update(record, {
+                            status: 'cancelled',
+                            tasks: cancelledTasks,
+                            reason: String(controller.signal.reason ?? 'cancelled'),
+                        });
+                    }
+                    if (result.status === 'completed' && result.evidenceRefs.length === 0) {
+                        const failedTasks = [...record.snapshot.tasks];
+                        failedTasks[taskIndex] = {
+                            ...runningTask,
+                            status: 'failed',
+                            completedAt: now(),
+                            reason: 'Task completion requires Evidence.',
+                            evidenceRefs: [],
+                        };
+                        return update(record, {
+                            status: 'failed',
+                            tasks: failedTasks,
+                            reason: 'Task completion requires Evidence.',
+                        });
+                    }
+                    const tasks = [...record.snapshot.tasks];
+                    tasks[taskIndex] = {
+                        ...runningTask,
+                        status: result.status,
+                        completedAt: now(),
+                        reason: result.status === 'completed' ? undefined : result.reason,
+                        evidenceRefs: [...(result.evidenceRefs ?? [])],
+                    };
+                    if (result.status === 'blocked') {
+                        return update(record, { status: 'blocked', tasks, reason: result.reason });
+                    }
+                    if (result.status === 'failed') {
+                        return update(record, { status: 'failed', tasks, reason: result.reason });
+                    }
+                    update(record, { tasks });
+                }
+                return record.snapshot;
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    return record.snapshot;
+                const reason = error instanceof Error ? error.message : String(error);
+                const tasks = record.snapshot.tasks.map((task) => task.status === 'running'
+                    ? { ...task, status: 'failed', completedAt: now(), reason }
+                    : task);
+                return update(record, { status: 'failed', tasks, reason });
+            }
+            finally {
+                record.controller = undefined;
+                record.run = undefined;
+            }
+        })();
+        record.run = promise;
+        return promise;
+    };
+    return {
+        create(input) {
+            if (goals.has(input.goalId))
+                throw new Error(`Runtime goal ${input.goalId} already exists.`);
+            if (planGoals.has(input.sourcePlanId)) {
+                throw new Error(`Runtime plan ${input.sourcePlanId} already created goal ${planGoals.get(input.sourcePlanId)}.`);
+            }
+            if (input.tasks.length === 0)
+                throw new Error('Runtime goal requires at least one task.');
+            const createdAt = now();
+            const snapshot = {
+                goalId: input.goalId,
+                sourcePlanId: input.sourcePlanId,
+                sessionId: input.sessionId,
+                title: input.title,
+                goal: input.goal,
+                status: 'pending',
+                tasks: input.tasks.map((task) => ({ ...task, status: 'pending', evidenceRefs: [] })),
+                successCriteria: [...(input.successCriteria ?? [])],
+                createdAt,
+                updatedAt: createdAt,
+            };
+            const record = { snapshot, pauseRequested: false };
+            goals.set(input.goalId, record);
+            planGoals.set(input.sourcePlanId, input.goalId);
+            return publish(record, snapshot);
+        },
+        start(goalId) {
+            const record = requireGoal(goalId);
+            if (record.snapshot.status !== 'pending') {
+                throw new Error(`Runtime goal ${goalId} cannot start from ${record.snapshot.status}.`);
+            }
+            return run(record);
+        },
+        pause(goalId) {
+            const record = requireGoal(goalId);
+            if (record.snapshot.status !== 'running')
+                return record.snapshot;
+            record.pauseRequested = true;
+            return record.snapshot;
+        },
+        resume(goalId) {
+            const record = requireGoal(goalId);
+            if (record.snapshot.status === 'blocked') {
+                const tasks = record.snapshot.tasks.map((task) => task.status === 'blocked'
+                    ? { ...task, status: 'pending', startedAt: undefined, completedAt: undefined, reason: undefined }
+                    : task);
+                update(record, { status: 'paused', tasks, reason: undefined });
+            }
+            if (record.snapshot.status !== 'paused') {
+                throw new Error(`Runtime goal ${goalId} cannot resume from ${record.snapshot.status}.`);
+            }
+            return run(record);
+        },
+        cancel(goalId, reason = 'cancelled') {
+            const record = requireGoal(goalId);
+            const terminal = ['completed', 'failed', 'cancelled'];
+            if (terminal.includes(record.snapshot.status))
+                return record.snapshot;
+            record.controller?.abort(reason);
+            const tasks = record.snapshot.tasks.map((task) => task.status === 'pending' || task.status === 'running' || task.status === 'blocked'
+                ? { ...task, status: 'cancelled', completedAt: now(), reason }
+                : task);
+            return update(record, { status: 'cancelled', tasks, reason });
+        },
+        get(goalId) {
+            return goals.get(goalId)?.snapshot ?? null;
+        },
+        list() {
+            return [...goals.values()].map((record) => record.snapshot);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { RUNTIME_EVENT_PROTOCOL_VERSION } from './contracts.ts';
+export type { RuntimeEventProtocolVersion, RuntimeExecuteRequest, RuntimeExecutionContext, RuntimeToolCall, RuntimeToolResult, RuntimeSdk, RuntimeSdkApprovalDecision, RuntimeSdkApprovalPort, RuntimeSdkEvent, RuntimeSdkEventBase, RuntimeSdkEventInput, RuntimeSdkEventListener, RuntimeSdkEventType, RuntimeSdkSessionStartedEvent, RuntimeSdkMessageDeltaEvent, RuntimeSdkReasoningDeltaEvent, RuntimeSdkCompactionProgressEvent, RuntimeSdkContextAccountingEvent, RuntimeSdkMessageCompletedEvent, RuntimeSdkRuntimeErrorEvent, RuntimeSdkHookCompletedEvent, RuntimeSdkPermissionRequestedEvent, RuntimeSdkPermissionResolvedEvent, RuntimeSdkToolCompletedEvent, RuntimeSdkToolStartedEvent, RuntimeSdkExecuteRequest, RuntimeSdkExecutionContext, RuntimeSdkHookPayload, RuntimeSdkHookRecord, RuntimeSdkHookRunner, RuntimeSdkHostAdapter, RuntimeSdkOptions, RuntimeSdkPermissionRequest, RuntimeSdkProviderExecution, RuntimeSdkToolCall, RuntimeSdkToolResult, } from './contracts.ts';
+export type { RuntimePipeline, RuntimePipelineCompletedTurn, RuntimePipelineContinueTurn, RuntimePipelineEventSink, RuntimePipelineLifecycleObserver, RuntimePipelineModelAdapter, RuntimePipelineOptions, RuntimePipelineRunInput, RuntimePipelineRunResult, RuntimePipelineStatus, RuntimePipelineToolCall, RuntimePipelineToolCallsTurn, RuntimePipelineToolExecution, RuntimePipelineToolExecutor, RuntimePipelineTurnContext, RuntimePipelineTurnResult, } from './pipeline-contracts.ts';
+export { createRuntimePipeline } from './pipeline.ts';
+export { createRuntimeSdk } from './runtime.ts';
+export type { RuntimeSessionController, RuntimeSessionControllerOptions, RuntimeSessionResumeOptions, RuntimeSessionSnapshot, RuntimeSessionStartOptions, RuntimeSessionStatus, RuntimeSessionTurnHandle, RuntimeSessionTurnSnapshot, RuntimeTurnStatus, } from './session-contracts.ts';
+export { createRuntimeSessionController } from './session-controller.ts';
+export type { RuntimeGoalController, RuntimeGoalControllerOptions, RuntimeGoalCreateOptions, RuntimeGoalSnapshot, RuntimeGoalStatus, RuntimeGoalSuccessCriterion, RuntimeGoalTaskExecutionContext, RuntimeGoalTaskExecutionResult, RuntimeGoalTaskExecutor, RuntimeGoalTaskInput, RuntimeGoalTaskSnapshot, RuntimeGoalTaskStatus, } from './goal-contracts.ts';
+export { createRuntimeGoalController } from './goal-controller.ts';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { RUNTIME_EVENT_PROTOCOL_VERSION } from "./contracts.js";
+export { createRuntimePipeline } from "./pipeline.js";
+export { createRuntimeSdk } from "./runtime.js";
+export { createRuntimeSessionController } from "./session-controller.js";
+export { createRuntimeGoalController } from "./goal-controller.js";

package/dist/pipeline-contracts.d.ts

@@ -0,0 +1,92 @@
+import type { RuntimeSdkEvent, RuntimeSdkEventInput, RuntimeSdkToolResult } from './contracts.ts';
+export type RuntimePipelineStatus = 'completed' | 'stopped' | 'cancelled' | 'exhausted' | 'failed';
+export interface RuntimePipelineRunInput<TInput = unknown> {
+    readonly sessionId: string;
+    readonly streamId?: string;
+    readonly conversationId?: string;
+    readonly mode?: string;
+    readonly providerId?: string;
+    readonly model?: string;
+    readonly input: TInput;
+    readonly maxTurns?: number;
+}
+export interface RuntimePipelineToolCall<TPayload = unknown> {
+    readonly toolCallId: string;
+    readonly capabilityId?: string;
+    readonly name?: string;
+    readonly arguments?: unknown;
+    readonly payload?: TPayload;
+}
+export interface RuntimePipelineToolExecution<TCall extends RuntimePipelineToolCall = RuntimePipelineToolCall, TResult = RuntimeSdkToolResult> {
+    readonly call: TCall;
+    readonly result: TResult;
+    readonly terminal?: boolean;
+    readonly terminalReason?: string;
+}
+export interface RuntimePipelineTurnContext<TInput = unknown> {
+    readonly run: RuntimePipelineRunInput<TInput>;
+    readonly turn: number;
+    readonly signal?: AbortSignal;
+    readonly emit: (event: RuntimeSdkEventInput) => RuntimeSdkEvent | null;
+}
+export interface RuntimePipelineContinueTurn<TState> {
+    readonly kind: 'continue';
+    readonly state: TState;
+}
+export interface RuntimePipelineCompletedTurn<TState, TOutput = unknown> {
+    readonly kind: 'completed';
+    readonly state: TState;
+    readonly output?: TOutput;
+    readonly reason?: string;
+}
+export interface RuntimePipelineToolCallsTurn<TState, TCall extends RuntimePipelineToolCall = RuntimePipelineToolCall> {
+    readonly kind: 'tool_calls';
+    readonly state: TState;
+    readonly calls: readonly TCall[];
+}
+export type RuntimePipelineTurnResult<TState, TCall extends RuntimePipelineToolCall = RuntimePipelineToolCall, TOutput = unknown> = RuntimePipelineContinueTurn<TState> | RuntimePipelineCompletedTurn<TState, TOutput> | RuntimePipelineToolCallsTurn<TState, TCall>;
+export interface RuntimePipelineModelAdapter<TInput = unknown, TState = unknown, TCall extends RuntimePipelineToolCall = RuntimePipelineToolCall, TToolResult = RuntimeSdkToolResult, TOutput = unknown> {
+    initialize(input: RuntimePipelineRunInput<TInput>, context: RuntimePipelineTurnContext<TInput>): TState | Promise<TState>;
+    runTurn(state: TState, context: RuntimePipelineTurnContext<TInput>): RuntimePipelineTurnResult<TState, TCall, TOutput> | Promise<RuntimePipelineTurnResult<TState, TCall, TOutput>>;
+    applyToolResults(state: TState, executions: readonly RuntimePipelineToolExecution<TCall, TToolResult>[], context: RuntimePipelineTurnContext<TInput>): TState | Promise<TState>;
+    onCompleted?(state: TState, output: TOutput | undefined, context: RuntimePipelineTurnContext<TInput>): void | Promise<void>;
+    onStopped?(state: TState, executions: readonly RuntimePipelineToolExecution<TCall, TToolResult>[], context: RuntimePipelineTurnContext<TInput>): void | Promise<void>;
+    onCancelled?(state: TState | undefined, context: RuntimePipelineTurnContext<TInput>): void | Promise<void>;
+    onExhausted?(state: TState, context: RuntimePipelineTurnContext<TInput>): void | Promise<void>;
+}
+export interface RuntimePipelineToolExecutor<TInput = unknown, TCall extends RuntimePipelineToolCall = RuntimePipelineToolCall, TToolResult = RuntimeSdkToolResult> {
+    execute(call: TCall, context: RuntimePipelineTurnContext<TInput> & {
+        readonly index: number;
+    }): RuntimePipelineToolExecution<TCall, TToolResult> | Promise<RuntimePipelineToolExecution<TCall, TToolResult>>;
+}
+export interface RuntimePipelineEventSink {
+    emit(event: RuntimeSdkEventInput): RuntimeSdkEvent | null;
+}
+/**
+ * Observes stable Runtime Pipeline state transitions after the model adapter
+ * has committed them. Hosts use this seam for projections and presentation;
+ * observer failures never change pipeline execution.
+ */
+export interface RuntimePipelineLifecycleObserver<TInput = unknown, TState = unknown, TCall extends RuntimePipelineToolCall = RuntimePipelineToolCall, TToolResult = RuntimeSdkToolResult> {
+    toolResultsApplied?(state: TState, executions: readonly RuntimePipelineToolExecution<TCall, TToolResult>[], context: RuntimePipelineTurnContext<TInput>): void | Promise<void>;
+}
+export interface RuntimePipelineOptions<TInput = unknown, TState = unknown, TCall extends RuntimePipelineToolCall = RuntimePipelineToolCall, TToolResult = RuntimeSdkToolResult, TOutput = unknown> {
+    readonly model: RuntimePipelineModelAdapter<TInput, TState, TCall, TToolResult, TOutput>;
+    readonly tools: RuntimePipelineToolExecutor<TInput, TCall, TToolResult>;
+    readonly events?: RuntimePipelineEventSink;
+    readonly lifecycle?: RuntimePipelineLifecycleObserver<TInput, TState, TCall, TToolResult>;
+    readonly defaultMaxTurns?: number;
+}
+export interface RuntimePipelineRunResult<TState = unknown, TOutput = unknown> {
+    readonly status: RuntimePipelineStatus;
+    readonly state?: TState;
+    readonly output?: TOutput;
+    readonly turns: number;
+    readonly toolCalls: number;
+    readonly reason?: string;
+}
+export interface RuntimePipeline<TInput = unknown, TState = unknown, TOutput = unknown> {
+    run(input: RuntimePipelineRunInput<TInput>, context?: {
+        readonly signal?: AbortSignal;
+    }): Promise<RuntimePipelineRunResult<TState, TOutput>>;
+}

package/dist/pipeline-contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/pipeline.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimePipeline, RuntimePipelineOptions, RuntimePipelineToolCall } from './pipeline-contracts.ts';
+export declare function createRuntimePipeline<TInput = unknown, TState = unknown, TCall extends RuntimePipelineToolCall = RuntimePipelineToolCall, TToolResult = unknown, TOutput = unknown>(options: RuntimePipelineOptions<TInput, TState, TCall, TToolResult, TOutput>): RuntimePipeline<TInput, TState, TOutput>;

package/dist/pipeline.js

@@ -0,0 +1,181 @@
+const DEFAULT_MAX_TURNS = 64;
+function normalizeMaxTurns(value, fallback) {
+    if (value === Number.POSITIVE_INFINITY)
+        return value;
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.max(1, Math.floor(value));
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message || error.name;
+    return String(error || 'runtime_pipeline_error');
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        const error = new Error('Aborted');
+        error.name = 'AbortError';
+        throw error;
+    }
+}
+export function createRuntimePipeline(options) {
+    if (!options?.model)
+        throw new Error('RuntimePipeline requires a model adapter.');
+    if (!options?.tools)
+        throw new Error('RuntimePipeline requires a tool executor.');
+    const defaultMaxTurns = normalizeMaxTurns(options.defaultMaxTurns, DEFAULT_MAX_TURNS);
+    return {
+        async run(input, context = {}) {
+            if (!input?.sessionId)
+                throw new Error('RuntimePipeline run requires sessionId.');
+            const signal = context.signal;
+            const maxTurns = normalizeMaxTurns(input.maxTurns, defaultMaxTurns);
+            let state;
+            let turns = 0;
+            let toolCalls = 0;
+            const emit = (event) => {
+                try {
+                    return options.events?.emit(event) ?? null;
+                }
+                catch {
+                    return null;
+                }
+            };
+            const eventBase = {
+                sessionId: input.sessionId,
+                ...(input.streamId ? { streamId: input.streamId } : {}),
+                ...(input.conversationId ? { conversationId: input.conversationId } : {}),
+            };
+            const turnContext = (turn) => ({
+                run: input,
+                turn,
+                signal,
+                emit,
+            });
+            try {
+                throwIfAborted(signal);
+                emit({
+                    type: 'session.started',
+                    ...eventBase,
+                    ...(input.mode ? { mode: input.mode } : {}),
+                    ...(input.providerId ? { providerId: input.providerId } : {}),
+                    ...(input.model ? { model: input.model } : {}),
+                });
+                state = await options.model.initialize(input, turnContext(0));
+                for (let turn = 0; turn < maxTurns; turn += 1) {
+                    throwIfAborted(signal);
+                    turns = turn + 1;
+                    const currentContext = turnContext(turn);
+                    const outcome = await options.model.runTurn(state, currentContext);
+                    state = outcome.state;
+                    if (outcome.kind === 'continue')
+                        continue;
+                    if (outcome.kind === 'completed') {
+                        await options.model.onCompleted?.(state, outcome.output, currentContext);
+                        if (input.streamId) {
+                            emit({
+                                type: 'message.completed',
+                                ...eventBase,
+                                streamId: input.streamId,
+                                ...(outcome.reason ? { finishReason: outcome.reason } : {}),
+                            });
+                        }
+                        return {
+                            status: 'completed',
+                            state,
+                            output: outcome.output,
+                            turns,
+                            toolCalls,
+                            ...(outcome.reason ? { reason: outcome.reason } : {}),
+                        };
+                    }
+                    const executions = [];
+                    for (const [index, call] of outcome.calls.entries()) {
+                        throwIfAborted(signal);
+                        const execution = await options.tools.execute(call, {
+                            ...currentContext,
+                            index,
+                        });
+                        executions.push(execution);
+                        toolCalls += 1;
+                    }
+                    state = await options.model.applyToolResults(state, executions, currentContext);
+                    try {
+                        await options.lifecycle?.toolResultsApplied?.(state, executions, currentContext);
+                    }
+                    catch {
+                        // Lifecycle observers publish projections/presentation only. Their
+                        // failure must not change model or tool execution semantics.
+                    }
+                    const terminalExecution = executions.find((execution) => execution.terminal);
+                    if (terminalExecution) {
+                        await options.model.onStopped?.(state, executions, currentContext);
+                        if (input.streamId) {
+                            emit({
+                                type: 'message.completed',
+                                ...eventBase,
+                                streamId: input.streamId,
+                                finishReason: terminalExecution.terminalReason || 'tool_requested_stop',
+                            });
+                        }
+                        return {
+                            status: 'stopped',
+                            state,
+                            turns,
+                            toolCalls,
+                            reason: terminalExecution.terminalReason || 'tool_requested_stop',
+                        };
+                    }
+                }
+                const exhaustedContext = turnContext(turns);
+                await options.model.onExhausted?.(state, exhaustedContext);
+                const exhaustedReason = 'max_turns_exceeded';
+                emit({
+                    type: 'runtime.error',
+                    ...eventBase,
+                    code: exhaustedReason,
+                    message: exhaustedReason,
+                });
+                return {
+                    status: 'exhausted',
+                    state,
+                    turns,
+                    toolCalls,
+                    reason: exhaustedReason,
+                };
+            }
+            catch (error) {
+                if (signal?.aborted || isAbortError(error)) {
+                    const cancelledContext = turnContext(turns);
+                    await options.model.onCancelled?.(state, cancelledContext);
+                    return {
+                        status: 'cancelled',
+                        state,
+                        turns,
+                        toolCalls,
+                        reason: 'aborted',
+                    };
+                }
+                const detail = errorMessage(error);
+                emit({
+                    type: 'runtime.error',
+                    ...eventBase,
+                    code: 'runtime_pipeline_error',
+                    message: detail,
+                });
+                // Preserve partial state (already-executed tools / model messages) so
+                // hosts can recover instead of discarding progress on provider stream errors.
+                return {
+                    status: 'failed',
+                    state,
+                    turns,
+                    toolCalls,
+                    reason: detail,
+                };
+            }
+        },
+    };
+}

package/dist/runtime.d.ts

@@ -0,0 +1,2 @@
+import { type RuntimeSdk, type RuntimeSdkOptions } from './contracts.ts';
+export declare function createRuntimeSdk(options: RuntimeSdkOptions): RuntimeSdk;

package/dist/runtime.js

@@ -0,0 +1,141 @@
+import { mostRestrictiveHookDecision } from '@peer-agent/runtime-core';
+import { RUNTIME_EVENT_PROTOCOL_VERSION, } from "./contracts.js";
+function normalizeRecords(records) {
+    return Array.isArray(records) ? records : [];
+}
+function createRuntimeEventId(sequence) {
+    const randomId = globalThis.crypto?.randomUUID?.();
+    return randomId ? `runtime-event-${randomId}` : `runtime-event-${Date.now()}-${sequence}`;
+}
+export function createRuntimeSdk(options) {
+    if (!options?.host || typeof options.host.executeProvider !== 'function') {
+        throw new TypeError('Runtime SDK requires a host.executeProvider adapter.');
+    }
+    if (typeof options.host.createBlockedExecution !== 'function') {
+        throw new TypeError('Runtime SDK requires a host.createBlockedExecution adapter.');
+    }
+    const listeners = new Set();
+    const now = options.now ?? (() => new Date().toISOString());
+    let sequence = 0;
+    function emit(event) {
+        const nextSequence = ++sequence;
+        const nextEvent = {
+            ...event,
+            protocolVersion: RUNTIME_EVENT_PROTOCOL_VERSION,
+            eventId: createRuntimeEventId(nextSequence),
+            sequence: nextSequence,
+            occurredAt: now(),
+        };
+        for (const listener of listeners) {
+            try {
+                listener(nextEvent);
+            }
+            catch {
+                // Runtime events are observational. A broken subscriber must not interrupt execution.
+            }
+        }
+        return nextEvent;
+    }
+    function subscribe(listener) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+    }
+    async function execute(request, context = {}) {
+        const call = request?.call;
+        if (!call?.toolCallId || !call?.capabilityId) {
+            throw new TypeError('Runtime SDK execute requires call.toolCallId and call.capabilityId.');
+        }
+        const eventBase = {
+            toolCallId: call.toolCallId,
+            capabilityId: call.capabilityId,
+            sessionId: request.sessionId,
+            projectionId: request.projectionId,
+            conversationId: request.conversationId,
+        };
+        const hookPayload = {
+            sessionId: request.sessionId,
+            projectionId: request.projectionId,
+            conversationId: request.conversationId,
+            call,
+        };
+        emit({ type: 'tool.started', ...eventBase });
+        const preRecords = normalizeRecords(options.host.hookRunner?.runPreToolUse
+            ? await options.host.hookRunner.runPreToolUse(hookPayload)
+            : []);
+        const preDecision = mostRestrictiveHookDecision(preRecords);
+        emit({
+            type: 'hook.completed',
+            ...eventBase,
+            phase: 'PreToolUse',
+            decision: preDecision,
+            records: preRecords,
+        });
+        if (preDecision === 'deny') {
+            const blocked = options.host.createBlockedExecution({
+                request,
+                context,
+                decision: 'deny',
+                reason: preRecords.find((record) => record.decision === 'deny')?.reason ?? 'hook_denied',
+            });
+            const result = options.host.appendHookEvidence
+                ? options.host.appendHookEvidence(blocked.result, preRecords, preDecision)
+                : blocked.result;
+            const resolvedBlocked = { ...blocked, result };
+            emit({ type: 'tool.completed', ...eventBase, decision: 'deny', result });
+            return resolvedBlocked;
+        }
+        if (preDecision === 'ask') {
+            const approvalRequest = {
+                kind: 'hook',
+                hookEvent: 'PreToolUse',
+                call,
+                toolCallId: call.toolCallId,
+                capabilityId: call.capabilityId,
+                args: call.arguments ?? call.argumentsPreview ?? {},
+                workspacePath: context.workspaceRoot ?? options.workspaceRoot,
+                reason: preRecords.find((record) => record.decision === 'ask')?.reason ?? 'hook_approval_required',
+            };
+            emit({ type: 'permission.requested', ...eventBase, decision: 'ask' });
+            const approval = options.host.approvalPort
+                ? await options.host.approvalPort.requestApproval(approvalRequest, context)
+                : { decision: 'ask' };
+            emit({ type: 'permission.resolved', ...eventBase, decision: approval.decision });
+            if (approval.decision !== 'allow') {
+                const blocked = options.host.createBlockedExecution({
+                    request,
+                    context,
+                    decision: approval.decision,
+                    reason: approval.decision === 'deny' ? 'hook_approval_denied' : 'hook_approval_required',
+                    approval,
+                });
+                const result = options.host.appendHookEvidence
+                    ? options.host.appendHookEvidence(blocked.result, preRecords, preDecision)
+                    : blocked.result;
+                const resolvedBlocked = { ...blocked, result };
+                emit({ type: 'tool.completed', ...eventBase, decision: approval.decision, result });
+                return resolvedBlocked;
+            }
+        }
+        const execution = await options.host.executeProvider(request, context);
+        const postRecords = normalizeRecords(options.host.hookRunner?.runPostToolUse
+            ? await options.host.hookRunner.runPostToolUse({
+                ...hookPayload,
+                result: execution.result,
+            })
+            : []);
+        emit({
+            type: 'hook.completed',
+            ...eventBase,
+            phase: 'PostToolUse',
+            decision: mostRestrictiveHookDecision(postRecords),
+            records: postRecords,
+        });
+        const result = options.host.appendHookEvidence
+            ? options.host.appendHookEvidence(execution.result, [...preRecords, ...postRecords], preDecision)
+            : execution.result;
+        const resolvedExecution = { ...execution, result };
+        emit({ type: 'tool.completed', ...eventBase, decision: preDecision, result });
+        return resolvedExecution;
+    }
+    return { emit, execute, subscribe };
+}

package/dist/session-contracts.d.ts

@@ -0,0 +1,57 @@
+export type RuntimeSessionStatus = 'idle' | 'running';
+export type RuntimeTurnStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+export interface RuntimeSessionTurnSnapshot {
+    readonly turnId: string;
+    readonly turnIndex: number;
+    readonly streamId?: string;
+    readonly status: RuntimeTurnStatus;
+    readonly startedAt: string;
+    readonly completedAt?: string;
+    readonly reason?: string;
+}
+export interface RuntimeSessionSnapshot {
+    readonly sessionId: string;
+    readonly conversationId?: string;
+    readonly status: RuntimeSessionStatus;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly nextTurnIndex: number;
+    readonly activeTurn?: RuntimeSessionTurnSnapshot;
+    readonly lastTurn?: RuntimeSessionTurnSnapshot;
+}
+export interface RuntimeSessionStartOptions {
+    readonly sessionId: string;
+    readonly conversationId?: string;
+    readonly streamId?: string;
+    readonly signal?: AbortSignal;
+}
+export interface RuntimeSessionResumeOptions {
+    readonly sessionId: string;
+    readonly streamId?: string;
+    readonly signal?: AbortSignal;
+}
+export interface RuntimeSessionTurnHandle {
+    readonly sessionId: string;
+    readonly conversationId?: string;
+    readonly turnId: string;
+    readonly turnIndex: number;
+    readonly streamId?: string;
+    readonly signal: AbortSignal;
+    complete(): RuntimeSessionSnapshot;
+    fail(reason?: string): RuntimeSessionSnapshot;
+    cancel(reason?: string): RuntimeSessionSnapshot;
+    snapshot(): RuntimeSessionSnapshot;
+}
+export interface RuntimeSessionControllerOptions {
+    readonly createTurnId?: (sessionId: string, turnIndex: number) => string;
+    readonly now?: () => string;
+    readonly onChange?: (snapshot: RuntimeSessionSnapshot) => void;
+}
+export interface RuntimeSessionController {
+    start(options: RuntimeSessionStartOptions): RuntimeSessionTurnHandle;
+    resume(options: RuntimeSessionResumeOptions): RuntimeSessionTurnHandle;
+    cancel(sessionId: string, reason?: string): RuntimeSessionSnapshot | null;
+    get(sessionId: string): RuntimeSessionSnapshot | null;
+    list(): readonly RuntimeSessionSnapshot[];
+    delete(sessionId: string): boolean;
+}

package/dist/session-contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/session-controller.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeSessionController, RuntimeSessionControllerOptions } from './session-contracts.ts';
+export declare function createRuntimeSessionController(options?: RuntimeSessionControllerOptions): RuntimeSessionController;

package/dist/session-controller.js

@@ -0,0 +1,138 @@
+function normalizeReason(reason, fallback = 'aborted') {
+    return typeof reason === 'string' && reason.trim() ? reason.trim() : fallback;
+}
+function snapshotSession(record) {
+    return {
+        sessionId: record.sessionId,
+        ...(record.conversationId ? { conversationId: record.conversationId } : {}),
+        status: record.activeTurn ? 'running' : 'idle',
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        nextTurnIndex: record.nextTurnIndex,
+        ...(record.activeTurn ? { activeTurn: { ...record.activeTurn.snapshot } } : {}),
+        ...(record.lastTurn ? { lastTurn: { ...record.lastTurn } } : {}),
+    };
+}
+export function createRuntimeSessionController(options = {}) {
+    const sessions = new Map();
+    const now = options.now ?? (() => new Date().toISOString());
+    const createTurnId = options.createTurnId
+        ?? ((sessionId, turnIndex) => `${sessionId}:turn:${turnIndex}`);
+    const publish = (record) => {
+        const snapshot = snapshotSession(record);
+        options.onChange?.(snapshot);
+        return snapshot;
+    };
+    const finishTurn = (record, activeTurn, status, reason, abortSignal = false) => {
+        if (record.activeTurn !== activeTurn)
+            return snapshotSession(record);
+        activeTurn.detachExternalSignal?.();
+        if (abortSignal && !activeTurn.controller.signal.aborted) {
+            activeTurn.controller.abort(reason);
+        }
+        const completedAt = now();
+        record.activeTurn = undefined;
+        record.lastTurn = {
+            ...activeTurn.snapshot,
+            status,
+            completedAt,
+            ...(reason ? { reason } : {}),
+        };
+        record.updatedAt = completedAt;
+        return publish(record);
+    };
+    const beginTurn = (record, options, startedAt = now()) => {
+        if (record.activeTurn) {
+            throw new Error(`Runtime session ${record.sessionId} already has an active turn`);
+        }
+        const turnIndex = record.nextTurnIndex;
+        const turnId = createTurnId(record.sessionId, turnIndex);
+        const controller = new AbortController();
+        const turnSnapshot = {
+            turnId,
+            turnIndex,
+            ...(options.streamId ? { streamId: options.streamId } : {}),
+            status: 'running',
+            startedAt,
+        };
+        const activeTurn = { snapshot: turnSnapshot, controller };
+        record.activeTurn = activeTurn;
+        record.nextTurnIndex = turnIndex + 1;
+        record.updatedAt = startedAt;
+        const cancelFromExternalSignal = () => {
+            finishTurn(record, activeTurn, 'cancelled', normalizeReason(options.signal?.reason, 'host_aborted'), true);
+        };
+        if (options.signal) {
+            if (options.signal.aborted) {
+                cancelFromExternalSignal();
+            }
+            else {
+                options.signal.addEventListener('abort', cancelFromExternalSignal, { once: true });
+                activeTurn.detachExternalSignal = () => {
+                    options.signal?.removeEventListener('abort', cancelFromExternalSignal);
+                };
+            }
+        }
+        if (record.activeTurn === activeTurn)
+            publish(record);
+        return {
+            sessionId: record.sessionId,
+            ...(record.conversationId ? { conversationId: record.conversationId } : {}),
+            turnId,
+            turnIndex,
+            ...(options.streamId ? { streamId: options.streamId } : {}),
+            signal: controller.signal,
+            complete: () => finishTurn(record, activeTurn, 'completed'),
+            fail: (reason) => finishTurn(record, activeTurn, 'failed', reason, true),
+            cancel: (reason) => finishTurn(record, activeTurn, 'cancelled', normalizeReason(reason), true),
+            snapshot: () => snapshotSession(record),
+        };
+    };
+    return {
+        start(startOptions) {
+            if (sessions.has(startOptions.sessionId)) {
+                throw new Error(`Runtime session ${startOptions.sessionId} already exists`);
+            }
+            const startedAt = now();
+            const record = {
+                sessionId: startOptions.sessionId,
+                ...(startOptions.conversationId
+                    ? { conversationId: startOptions.conversationId }
+                    : {}),
+                createdAt: startedAt,
+                updatedAt: startedAt,
+                nextTurnIndex: 0,
+            };
+            sessions.set(record.sessionId, record);
+            return beginTurn(record, startOptions, startedAt);
+        },
+        resume(resumeOptions) {
+            const record = sessions.get(resumeOptions.sessionId);
+            if (!record) {
+                throw new Error(`Runtime session ${resumeOptions.sessionId} does not exist`);
+            }
+            return beginTurn(record, resumeOptions);
+        },
+        cancel(sessionId, reason = 'aborted') {
+            const record = sessions.get(sessionId);
+            if (!record)
+                return null;
+            if (!record.activeTurn)
+                return snapshotSession(record);
+            return finishTurn(record, record.activeTurn, 'cancelled', normalizeReason(reason), true);
+        },
+        get(sessionId) {
+            const record = sessions.get(sessionId);
+            return record ? snapshotSession(record) : null;
+        },
+        list() {
+            return [...sessions.values()].map(snapshotSession);
+        },
+        delete(sessionId) {
+            const record = sessions.get(sessionId);
+            if (!record || record.activeTurn)
+                return false;
+            return sessions.delete(sessionId);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@peer-agent/runtime-sdk",
+  "version": "0.0.1-beta.43",
+  "description": "Public host-neutral orchestration SDK for Peer Agent runtimes.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yinLiangDream/Peer-Agent.git",
+    "directory": "packages/runtime-sdk"
+  },
+  "homepage": "https://github.com/yinLiangDream/Peer-Agent#readme",
+  "bugs": {
+    "url": "https://github.com/yinLiangDream/Peer-Agent/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@peer-agent/protocol": "^0.0.1-beta.43",
+    "@peer-agent/runtime-core": "^0.0.1-beta.43"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test src/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}