@agentstorm/platform-protocol 0.2.5

package/dist/agent-types.d.ts

@@ -0,0 +1,451 @@
+import type { AgentAttachment } from "./messages.js";
+export type AgentProvider = string;
+export interface AgentMetadata {
+    [key: string]: unknown;
+}
+export type AgentProviderNotice = {
+    type: "info";
+    message: string;
+} | {
+    type: "warning";
+    message: string;
+} | {
+    type: "error";
+    message: string;
+};
+/**
+ * Stdio-based MCP server (spawns a subprocess).
+ */
+export interface McpStdioServerConfig {
+    type: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /**
+     * When true, all tools from this server are always included in the prompt
+     * and never deferred behind tool search. Honored by the Claude provider.
+     */
+    alwaysLoad?: boolean;
+}
+/**
+ * HTTP-based MCP server.
+ */
+export interface McpHttpServerConfig {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+    /**
+     * When true, all tools from this server are always included in the prompt
+     * and never deferred behind tool search. Honored by the Claude provider.
+     */
+    alwaysLoad?: boolean;
+}
+/**
+ * SSE-based MCP server (Server-Sent Events over HTTP).
+ */
+export interface McpSseServerConfig {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+    /**
+     * When true, all tools from this server are always included in the prompt
+     * and never deferred behind tool search. Honored by the Claude provider.
+     */
+    alwaysLoad?: boolean;
+}
+/**
+ * Canonical MCP server configuration.
+ * Discriminated union by `type` field.
+ * Each provider normalizes this to their expected format.
+ */
+export type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig | McpSseServerConfig;
+export interface AgentMode {
+    id: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    colorTier?: string;
+}
+export type ProviderStatus = "ready" | "loading" | "error" | "unavailable";
+export interface AgentModelDefinition {
+    provider: AgentProvider;
+    id: string;
+    label: string;
+    description?: string;
+    isDefault?: boolean;
+    metadata?: AgentMetadata;
+    contextWindowMaxTokens?: number;
+    thinkingOptions?: AgentSelectOption[];
+    defaultThinkingOptionId?: string;
+}
+export interface AgentSelectOption {
+    id: string;
+    label: string;
+    description?: string;
+    isDefault?: boolean;
+    metadata?: AgentMetadata;
+}
+export declare function normalizeAgentModelDefinition(model: AgentModelDefinition): AgentModelDefinition;
+export interface ProviderSnapshotEntry {
+    provider: AgentProvider;
+    status: ProviderStatus;
+    enabled: boolean;
+    source?: "builtin" | "custom";
+    error?: string;
+    models?: AgentModelDefinition[];
+    modes?: AgentMode[];
+    fetchedAt?: string;
+    label?: string;
+    description?: string;
+    defaultModeId?: string | null;
+}
+export interface AgentFeatureToggle {
+    type: "toggle";
+    id: string;
+    label: string;
+    description?: string;
+    tooltip?: string;
+    icon?: string;
+    value: boolean;
+}
+export interface AgentFeatureSelect {
+    type: "select";
+    id: string;
+    label: string;
+    description?: string;
+    tooltip?: string;
+    icon?: string;
+    value: string | null;
+    options: AgentSelectOption[];
+}
+export type AgentFeature = AgentFeatureToggle | AgentFeatureSelect;
+export interface AgentCapabilityFlags {
+    [capability: string]: boolean | undefined;
+    supportsStreaming: boolean;
+    supportsSessionPersistence: boolean;
+    supportsSessionListing?: boolean;
+    supportsDynamicModes: boolean;
+    supportsMcpServers: boolean;
+    supportsReasoningStream: boolean;
+    supportsToolInvocations: boolean;
+    supportsRewindConversation?: boolean;
+    supportsRewindFiles?: boolean;
+    supportsRewindBoth?: boolean;
+}
+export interface AgentPersistenceHandle {
+    provider: AgentProvider;
+    sessionId: string;
+    /** Provider specific handle (Codex thread id, Claude resume token, etc). */
+    nativeHandle?: string;
+    metadata?: AgentMetadata;
+}
+export type AgentPromptContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | AgentAttachment;
+export type AgentPromptInput = string | AgentPromptContentBlock[];
+export interface AgentRunOptions {
+    outputSchema?: unknown;
+    resumeFrom?: AgentPersistenceHandle;
+    maxThinkingTokens?: number;
+}
+export interface AgentUsage {
+    inputTokens?: number;
+    cachedInputTokens?: number;
+    outputTokens?: number;
+    totalCostUsd?: number;
+    contextWindowMaxTokens?: number;
+    contextWindowUsedTokens?: number;
+}
+export declare const TOOL_CALL_ICON_NAMES: readonly ["wrench", "square_terminal", "eye", "pencil", "search", "bot", "sparkles", "brain", "mic_vocal"];
+export type ToolCallIconName = (typeof TOOL_CALL_ICON_NAMES)[number];
+export type ToolCallDetail = {
+    type: "shell";
+    command: string;
+    cwd?: string;
+    output?: string;
+    exitCode?: number | null;
+} | {
+    type: "read";
+    filePath: string;
+    content?: string;
+    offset?: number;
+    limit?: number;
+} | {
+    type: "edit";
+    filePath: string;
+    oldString?: string;
+    newString?: string;
+    unifiedDiff?: string;
+} | {
+    type: "write";
+    filePath: string;
+    content?: string;
+} | {
+    type: "search";
+    query: string;
+    toolName?: "search" | "grep" | "glob" | "web_search";
+    content?: string;
+    filePaths?: string[];
+    webResults?: Array<{
+        title: string;
+        url: string;
+    }>;
+    annotations?: string[];
+    numFiles?: number;
+    numMatches?: number;
+    durationMs?: number;
+    durationSeconds?: number;
+    truncated?: boolean;
+    mode?: "content" | "files_with_matches" | "count";
+} | {
+    type: "fetch";
+    url: string;
+    prompt?: string;
+    result?: string;
+    code?: number;
+    codeText?: string;
+    bytes?: number;
+    durationMs?: number;
+} | {
+    type: "worktree_setup";
+    worktreePath: string;
+    branchName: string;
+    log: string;
+    commands: Array<{
+        index: number;
+        command: string;
+        cwd: string;
+        log: string;
+        status: "running" | "completed" | "failed";
+        exitCode: number | null;
+        durationMs?: number;
+    }>;
+    truncated?: boolean;
+} | {
+    type: "sub_agent";
+    subAgentType?: string;
+    description?: string;
+    childSessionId?: string;
+    log: string;
+    actions?: Array<{
+        index: number;
+        toolName: string;
+        summary?: string;
+    }>;
+} | {
+    type: "plain_text";
+    label?: string;
+    text?: string;
+    icon?: ToolCallIconName;
+} | {
+    type: "plan";
+    text: string;
+} | {
+    type: "unknown";
+    input: unknown;
+    output: unknown;
+};
+interface ToolCallBase {
+    [key: string]: unknown;
+    type: "tool_call";
+    callId: string;
+    name: string;
+    detail: ToolCallDetail;
+    metadata?: Record<string, unknown>;
+}
+type ToolCallRunningTimelineItem = ToolCallBase & {
+    status: "running";
+    error: null;
+};
+type ToolCallCompletedTimelineItem = ToolCallBase & {
+    status: "completed";
+    error: null;
+};
+type ToolCallFailedTimelineItem = ToolCallBase & {
+    status: "failed";
+    error: unknown;
+};
+type ToolCallCanceledTimelineItem = ToolCallBase & {
+    status: "canceled";
+    error: null;
+};
+export type ToolCallTimelineItem = ToolCallRunningTimelineItem | ToolCallCompletedTimelineItem | ToolCallFailedTimelineItem | ToolCallCanceledTimelineItem;
+export interface CompactionTimelineItem {
+    [key: string]: unknown;
+    type: "compaction";
+    status: "loading" | "completed";
+    trigger?: "auto" | "manual";
+    preTokens?: number;
+}
+export type AgentTimelineItem = {
+    type: "user_message";
+    text: string;
+    messageId?: string;
+    clientMessageId?: string;
+} | {
+    type: "assistant_message";
+    text: string;
+    messageId?: string;
+} | {
+    type: "reasoning";
+    text: string;
+} | ToolCallTimelineItem | {
+    type: "todo";
+    items: {
+        text: string;
+        completed: boolean;
+    }[];
+} | {
+    type: "error";
+    message: string;
+} | CompactionTimelineItem;
+export type AgentStreamEvent = {
+    type: "thread_started";
+    sessionId: string;
+    provider: AgentProvider;
+} | {
+    type: "turn_started";
+    provider: AgentProvider;
+    turnId?: string;
+} | {
+    type: "turn_completed";
+    provider: AgentProvider;
+    usage?: AgentUsage;
+    turnId?: string;
+} | {
+    type: "usage_updated";
+    provider: AgentProvider;
+    usage: AgentUsage;
+    turnId?: string;
+} | {
+    type: "mode_changed";
+    provider: AgentProvider;
+    currentModeId: string | null;
+    availableModes: AgentMode[];
+} | {
+    type: "model_changed";
+    provider: AgentProvider;
+    runtimeInfo: AgentRuntimeInfo;
+} | {
+    type: "thinking_option_changed";
+    provider: AgentProvider;
+    thinkingOptionId: string | null;
+} | {
+    type: "turn_failed";
+    provider: AgentProvider;
+    error: string;
+    code?: string;
+    diagnostic?: string;
+    turnId?: string;
+} | {
+    type: "turn_canceled";
+    provider: AgentProvider;
+    reason: string;
+    turnId?: string;
+} | {
+    type: "timeline";
+    item: AgentTimelineItem;
+    provider: AgentProvider;
+    turnId?: string;
+    timestamp?: string;
+} | {
+    type: "permission_requested";
+    provider: AgentProvider;
+    request: AgentPermissionRequest;
+    turnId?: string;
+} | {
+    type: "permission_resolved";
+    provider: AgentProvider;
+    requestId: string;
+    resolution: AgentPermissionResponse;
+    turnId?: string;
+} | {
+    type: "attention_required";
+    provider: AgentProvider;
+    reason: "finished" | "error" | "permission";
+    timestamp: string;
+};
+export declare function getAgentStreamEventTurnId(event: AgentStreamEvent): string | undefined;
+export type AgentPermissionRequestKind = "tool" | "plan" | "question" | "mode" | "other";
+export type AgentPermissionUpdate = AgentMetadata;
+export interface AgentPermissionAction {
+    id: string;
+    label: string;
+    behavior: "allow" | "deny";
+    variant?: "primary" | "secondary" | "danger";
+    intent?: "implement" | "implement_resume" | "dismiss";
+}
+export interface AgentPermissionRequest {
+    id: string;
+    provider: AgentProvider;
+    name: string;
+    kind: AgentPermissionRequestKind;
+    title?: string;
+    description?: string;
+    input?: AgentMetadata;
+    detail?: ToolCallDetail;
+    suggestions?: AgentPermissionUpdate[];
+    actions?: AgentPermissionAction[];
+    metadata?: AgentMetadata;
+}
+export type AgentPermissionResponse = {
+    behavior: "allow";
+    selectedActionId?: string;
+    updatedInput?: AgentMetadata;
+    updatedPermissions?: AgentPermissionUpdate[];
+} | {
+    behavior: "deny";
+    selectedActionId?: string;
+    message?: string;
+    interrupt?: boolean;
+};
+export interface AgentRunResult {
+    sessionId: string;
+    finalText: string;
+    usage?: AgentUsage;
+    timeline: AgentTimelineItem[];
+    canceled?: boolean;
+}
+export interface AgentSessionConfig {
+    provider: AgentProvider;
+    cwd: string;
+    /**
+     * Provider-agnostic system/developer instruction string.
+     * Mapped by each provider to its native instruction field.
+     */
+    systemPrompt?: string;
+    modeId?: string;
+    model?: string;
+    thinkingOptionId?: string;
+    featureValues?: Record<string, unknown>;
+    title?: string | null;
+    approvalPolicy?: string;
+    sandboxMode?: string;
+    networkAccess?: boolean;
+    webSearch?: boolean;
+    extra?: {
+        codex?: AgentMetadata;
+        claude?: AgentMetadata;
+    };
+    mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Internal agents are hidden from listings and don't trigger notifications.
+     * They are used for ephemeral system tasks like commit/PR generation.
+     */
+    internal?: boolean;
+}
+export interface AgentRuntimeInfo {
+    provider: AgentProvider;
+    sessionId: string | null;
+    model?: string | null;
+    thinkingOptionId?: string | null;
+    modeId?: string | null;
+    extra?: AgentMetadata;
+}
+export {};
+//# sourceMappingURL=agent-types.d.ts.map

package/dist/agent-types.js

@@ -0,0 +1,22 @@
+export function normalizeAgentModelDefinition(model) {
+    const defaultThinkingOptionId = model.defaultThinkingOptionId ?? model.thinkingOptions?.find((option) => option.isDefault)?.id;
+    if (!defaultThinkingOptionId || defaultThinkingOptionId === model.defaultThinkingOptionId) {
+        return model;
+    }
+    return { ...model, defaultThinkingOptionId };
+}
+export const TOOL_CALL_ICON_NAMES = [
+    "wrench",
+    "square_terminal",
+    "eye",
+    "pencil",
+    "search",
+    "bot",
+    "sparkles",
+    "brain",
+    "mic_vocal",
+];
+export function getAgentStreamEventTurnId(event) {
+    return "turnId" in event ? event.turnId : undefined;
+}
+//# sourceMappingURL=agent-types.js.map

package/dist/binary-frames/demux.d.ts

@@ -0,0 +1,11 @@
+import { type FileTransferFrame } from "./file-transfer.js";
+import { type TerminalStreamFrame } from "./terminal.js";
+export type BinaryFrame = {
+    kind: "terminal";
+    frame: TerminalStreamFrame;
+} | {
+    kind: "file_transfer";
+    frame: FileTransferFrame;
+};
+export declare function decodeBinaryFrame(bytes: Uint8Array): BinaryFrame | null;
+//# sourceMappingURL=demux.d.ts.map

package/dist/binary-frames/demux.js

@@ -0,0 +1,23 @@
+import { decodeFileTransferFrame, FileTransferOpcode, } from "./file-transfer.js";
+import { decodeTerminalStreamFrame, TerminalStreamOpcode, } from "./terminal.js";
+export function decodeBinaryFrame(bytes) {
+    switch (bytes[0]) {
+        case TerminalStreamOpcode.Output:
+        case TerminalStreamOpcode.Input:
+        case TerminalStreamOpcode.Resize:
+        case TerminalStreamOpcode.Snapshot:
+        case TerminalStreamOpcode.Restore: {
+            const frame = decodeTerminalStreamFrame(bytes);
+            return frame ? { kind: "terminal", frame } : null;
+        }
+        case FileTransferOpcode.FileBegin:
+        case FileTransferOpcode.FileChunk:
+        case FileTransferOpcode.FileEnd: {
+            const frame = decodeFileTransferFrame(bytes);
+            return frame ? { kind: "file_transfer", frame } : null;
+        }
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=demux.js.map

package/dist/binary-frames/file-transfer.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+export declare const FileTransferOpcode: {
+    readonly FileBegin: 16;
+    readonly FileChunk: 17;
+    readonly FileEnd: 18;
+};
+export type FileTransferOpcode = (typeof FileTransferOpcode)[keyof typeof FileTransferOpcode];
+export declare const FileBeginMetadataSchema: z.ZodObject<{
+    mime: z.ZodString;
+    size: z.ZodNumber;
+    encoding: z.ZodEnum<{
+        binary: "binary";
+        "utf-8": "utf-8";
+    }>;
+    modifiedAt: z.ZodString;
+    revision: z.ZodOptional<z.ZodString>;
+    fileName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export interface FileBegin {
+    opcode: typeof FileTransferOpcode.FileBegin;
+    requestId: string;
+    metadata: z.infer<typeof FileBeginMetadataSchema>;
+    payload: Uint8Array;
+}
+export interface FileChunk {
+    opcode: typeof FileTransferOpcode.FileChunk;
+    requestId: string;
+    payload: Uint8Array;
+}
+export interface FileEnd {
+    opcode: typeof FileTransferOpcode.FileEnd;
+    requestId: string;
+    payload: Uint8Array;
+}
+export type FileTransferFrame = FileBegin | FileChunk | FileEnd;
+type FileTransferFrameInput = {
+    opcode: typeof FileTransferOpcode.FileBegin;
+    requestId: string;
+    metadata: z.infer<typeof FileBeginMetadataSchema>;
+} | {
+    opcode: typeof FileTransferOpcode.FileChunk;
+    requestId: string;
+    payload?: Uint8Array | ArrayBuffer | string;
+} | {
+    opcode: typeof FileTransferOpcode.FileEnd;
+    requestId: string;
+};
+export declare function encodeFileTransferFrame(input: FileTransferFrameInput): Uint8Array;
+export declare function decodeFileTransferFrame(bytes: Uint8Array): FileTransferFrame | null;
+export {};
+//# sourceMappingURL=file-transfer.d.ts.map

package/dist/binary-frames/file-transfer.js

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { asUint8Array } from "./terminal.js";
+export const FileTransferOpcode = {
+    FileBegin: 0x10,
+    FileChunk: 0x11,
+    FileEnd: 0x12,
+};
+export const FileBeginMetadataSchema = z.object({
+    mime: z.string().min(1),
+    size: z.number().int().nonnegative(),
+    encoding: z.enum(["utf-8", "binary"]),
+    modifiedAt: z.string(),
+    revision: z.string().optional(),
+    fileName: z.string().optional(),
+});
+export function encodeFileTransferFrame(input) {
+    const requestId = encodeRequestId(input.requestId);
+    if (input.opcode === FileTransferOpcode.FileBegin) {
+        const metadata = encodeJsonPayload(input.metadata);
+        if (metadata.byteLength > 0xffff) {
+            throw new RangeError("FileBegin metadata is too long");
+        }
+        const bytes = new Uint8Array(4 + requestId.byteLength + metadata.byteLength);
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        bytes[0] = input.opcode;
+        bytes[1] = requestId.byteLength;
+        bytes.set(requestId, 2);
+        view.setUint16(2 + requestId.byteLength, metadata.byteLength);
+        bytes.set(metadata, 4 + requestId.byteLength);
+        return bytes;
+    }
+    const payload = input.opcode === FileTransferOpcode.FileChunk
+        ? (asUint8Array(input.payload ?? new Uint8Array()) ?? new Uint8Array())
+        : new Uint8Array();
+    const bytes = new Uint8Array(2 + requestId.byteLength + payload.byteLength);
+    bytes[0] = input.opcode;
+    bytes[1] = requestId.byteLength;
+    bytes.set(requestId, 2);
+    bytes.set(payload, 2 + requestId.byteLength);
+    return bytes;
+}
+export function decodeFileTransferFrame(bytes) {
+    if (bytes.byteLength < 2) {
+        return null;
+    }
+    const opcode = bytes[0];
+    if (!isFileTransferOpcode(opcode)) {
+        return null;
+    }
+    const requestIdLength = bytes[1];
+    if (requestIdLength === 0 || requestIdLength > bytes.byteLength - 2) {
+        return null;
+    }
+    const requestId = decodeRequestId(bytes.subarray(2, 2 + requestIdLength));
+    const body = bytes.subarray(2 + requestIdLength);
+    if (opcode === FileTransferOpcode.FileBegin) {
+        if (body.byteLength < 2) {
+            return null;
+        }
+        const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+        const metadataLength = view.getUint16(0);
+        if (metadataLength !== body.byteLength - 2) {
+            return null;
+        }
+        const metadataBytes = body.subarray(2);
+        const result = FileBeginMetadataSchema.safeParse(decodeJsonPayload(metadataBytes));
+        return result.success
+            ? { opcode, requestId, metadata: result.data, payload: new Uint8Array() }
+            : null;
+    }
+    if (opcode === FileTransferOpcode.FileChunk) {
+        return { opcode, requestId, payload: body };
+    }
+    if (body.byteLength !== 0) {
+        return null;
+    }
+    return { opcode, requestId, payload: new Uint8Array() };
+}
+function isFileTransferOpcode(value) {
+    return (value === FileTransferOpcode.FileBegin ||
+        value === FileTransferOpcode.FileChunk ||
+        value === FileTransferOpcode.FileEnd);
+}
+function encodeJsonPayload(value) {
+    return new TextEncoder().encode(JSON.stringify(value));
+}
+function encodeRequestId(requestId) {
+    const bytes = new TextEncoder().encode(requestId);
+    if (bytes.byteLength === 0) {
+        throw new RangeError("File transfer requestId is required");
+    }
+    if (bytes.byteLength > 0xff) {
+        throw new RangeError("File transfer requestId is too long");
+    }
+    return bytes;
+}
+function decodeRequestId(bytes) {
+    return new TextDecoder().decode(bytes);
+}
+function decodeJsonPayload(bytes) {
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=file-transfer.js.map

package/dist/binary-frames/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./demux.js";
+export * from "./file-transfer.js";
+export * from "./terminal.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/binary-frames/index.js

@@ -0,0 +1,4 @@
+export * from "./demux.js";
+export * from "./file-transfer.js";
+export * from "./terminal.js";
+//# sourceMappingURL=index.js.map