@peer-agent/runtime-sdk 0.1.0

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,148 @@
+# @peer-agent/runtime-sdk
+
+Public, host-neutral orchestration SDK for Peer Agent Runtime.
+
+The SDK owns execution ordering, session and turn lifecycle, structured cancellation, Runtime Event sequencing, Hook coordination, approval flow, Provider dispatch, and Evidence attachment. Hosts supply environment-specific implementations. The package does not depend on Electron, filesystem APIs, child processes, network clients, or UI frameworks.
+
+## Package family
+
+Install the SDK and its public package dependencies:
+
+```bash
+npm install @peer-agent/runtime-sdk
+```
+
+The published Runtime family is:
+
+| Package | Responsibility |
+| --- | --- |
+| `@peer-agent/protocol` | Serializable contracts shared by runtimes and clients |
+| `@peer-agent/runtime-core` | Capability, projection, permission, Hook, and Evidence primitives |
+| `@peer-agent/runtime-sdk` | Host-neutral orchestration, events, pipeline, and session lifecycle |
+
+`@peer-agent/runtime-node` is a host adapter and is not part of the initial public package family.
+
+## Requirements
+
+- Node.js 20 or newer
+- ESM
+- TypeScript 5.x when consuming type declarations
+
+Use package root exports only. Deep imports into `src` or `dist` are not public API.
+
+## Runtime Host Adapter
+
+A host provides capability execution and failure-result construction. Hook execution, human approval, and Evidence attachment are optional ports.
+
+```ts
+import {
+  createRuntimeSdk,
+  type RuntimeSdkHostAdapter,
+} from '@peer-agent/runtime-sdk';
+
+const host: RuntimeSdkHostAdapter = {
+  executeProvider: (request, context) => providerRegistry.execute(request, context),
+  createBlockedExecution: ({ request, decision, reason }) =>
+    makeBlockedExecution(request, decision, reason),
+  hookRunner,
+  approvalPort,
+  appendHookEvidence,
+};
+
+const runtime = createRuntimeSdk({ host });
+runtime.subscribe((event) => renderRuntimeEvent(event));
+const execution = await runtime.execute(request, context);
+```
+
+The governed tool path is:
+
+```text
+tool.started
+  -> PreToolUse Hook
+  -> optional human approval
+  -> Capability Provider
+  -> PostToolUse Hook
+  -> Evidence attachment
+  -> tool.completed
+```
+
+A Hook may tighten a decision from `allow` to `ask` or `deny`; it must not bypass a stricter permission decision. If `ask` has no approval port, execution fails closed.
+
+## Session Controller
+
+`RuntimeSessionController` owns stable session identity, monotonic turn indexes, turn IDs, and the AbortSignal used by Provider work.
+
+```ts
+import { createRuntimeSessionController } from '@peer-agent/runtime-sdk';
+
+const sessions = createRuntimeSessionController();
+
+const firstTurn = sessions.start({
+  sessionId: 'conversation-42',
+  conversationId: 'conversation-42',
+  streamId: 'stream-1',
+});
+await runProvider({ signal: firstTurn.signal });
+firstTurn.complete();
+
+const resumedTurn = sessions.resume({
+  sessionId: 'conversation-42',
+  streamId: 'stream-2',
+});
+resumedTurn.cancel('user_aborted');
+```
+
+Rules:
+
+- A session has at most one active turn.
+- `resume` keeps the session identity and increments `turnIndex`.
+- `cancel` and `fail` abort the SDK-owned signal.
+- A late `complete` cannot overwrite an existing `cancelled` or `failed` terminal state.
+- UI stream reattachment and replay remain host concerns; they are not Runtime resume semantics.
+
+## Runtime Pipeline
+
+`createRuntimePipeline` runs model turns and projected tool calls while preserving structured cancellation. A host adapter converts `cancelled` into platform-specific behavior such as Desktop `AbortError` or terminal UI state.
+
+```ts
+import { createRuntimePipeline } from '@peer-agent/runtime-sdk';
+
+const pipeline = createRuntimePipeline({
+  modelTurnRunner,
+  toolExecutor,
+  eventSink,
+});
+
+const result = await pipeline.run(turnContext, { signal });
+if (result.status === 'cancelled') {
+  // Convert only at the host boundary.
+}
+```
+
+## Runtime Event protocol
+
+Runtime Event v1 is identified by `RUNTIME_EVENT_PROTOCOL_VERSION`. One Runtime emitter assigns a monotonically increasing `sequence` to all emitted events. Session resume must continue on the same emitter when a host needs cross-turn ordering.
+
+Subscribers are observational: a subscriber failure does not interrupt Provider execution or delivery to other subscribers.
+
+## Compatibility policy
+
+- `@peer-agent/protocol`, `@peer-agent/runtime-core`, and `@peer-agent/runtime-sdk` follow SemVer independently from the Desktop and TUI products.
+- The initial public package family is versioned `0.1.0`.
+- The SDK declares compatible Protocol and Core ranges as normal package dependencies.
+- Breaking public root-export, event, session, or host-port changes require a SemVer minor bump while the packages remain `0.x`.
+- Runtime Event protocol changes require an explicit protocol version change and compatibility notes.
+- Source file paths, test helpers, Desktop adapters, and Node host internals are not public API.
+
+## Release verification
+
+The monorepo validates the exact tarballs rather than relying on workspace symlinks:
+
+```bash
+pnpm runtime:pack-check
+pnpm runtime:pack-smoke
+```
+
+These checks build and pack all three public packages, reject leaked source/test/Desktop files, install the tarballs into an empty offline project, run an ESM consumer, compile an external strict TypeScript consumer, verify dependency ranges, and confirm deep imports are blocked.
+
+Package metadata is prepared for public npm access, but registry publication is a separate explicit operation requiring scope permission, credentials, version, and dist-tag confirmation.

package/dist/contracts.d.ts

@@ -0,0 +1,151 @@
+import type { RuntimeDecision } from '@peer-agent/runtime-core';
+import type { 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';
+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;
+}
+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 | 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/index.d.ts

@@ -0,0 +1,7 @@
+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, 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, 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';

package/dist/index.js

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

package/dist/pipeline-contracts.d.ts

@@ -0,0 +1,83 @@
+import type { RuntimeSdkEvent, RuntimeSdkEventInput, RuntimeSdkToolResult } from './contracts.ts';
+export type RuntimePipelineStatus = 'completed' | 'stopped' | 'cancelled' | 'exhausted';
+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;
+}
+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 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,165 @@
+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);
+                    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',
+                    };
+                }
+                emit({
+                    type: 'runtime.error',
+                    ...eventBase,
+                    code: 'runtime_pipeline_error',
+                    message: errorMessage(error),
+                });
+                throw error;
+            }
+        },
+    };
+}

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,47 @@
+{
+  "name": "@peer-agent/runtime-sdk",
+  "version": "0.1.0",
+  "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"
+  ],
+  "dependencies": {
+    "@peer-agent/protocol": "^0.1.0",
+    "@peer-agent/runtime-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test src/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}