@getpaseo/protocol 0.1.84

package/README.md

@@ -0,0 +1,12 @@
+# @getpaseo/protocol
+
+Shared Paseo protocol schemas, codecs, and wire types.
+
+## Stability
+
+This package is public so Paseo's published packages can depend on it cleanly.
+It is not a stable public API yet.
+
+Schemas, exports, wire helpers, and types may change or disappear in any release
+without advance notice. Use it outside Paseo at your own risk until the package
+is explicitly documented as stable.

package/dist/agent-attention-notification.d.ts

@@ -0,0 +1,41 @@
+export type AgentAttentionReason = "finished" | "error" | "permission";
+export interface AgentAttentionNotificationData {
+    [key: string]: unknown;
+    serverId: string;
+    agentId: string;
+    reason: AgentAttentionReason;
+}
+export interface AgentAttentionNotificationPayload {
+    title: string;
+    body: string;
+    data: AgentAttentionNotificationData;
+}
+interface BuildAgentAttentionNotificationPayloadInput {
+    reason: AgentAttentionReason;
+    serverId: string;
+    agentId: string;
+    assistantMessage?: string | null;
+    permissionRequest?: NotificationPermissionRequest | null;
+}
+export interface NotificationPermissionRequest {
+    id: string;
+    provider: string;
+    name: string;
+    kind: "tool" | "plan" | "question" | "mode" | "other";
+    title?: string;
+    description?: string;
+    input?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export type AssistantTimelineItem = {
+    type: "assistant_message";
+    text: string;
+} | {
+    type: string;
+    text?: string;
+};
+export declare function findLatestAssistantMessageFromTimeline(timeline: readonly AssistantTimelineItem[]): string | null;
+export declare function findLatestPermissionRequest(pendingPermissions: ReadonlyMap<string, NotificationPermissionRequest>): NotificationPermissionRequest | null;
+export declare function buildAgentAttentionNotificationPayload(input: BuildAgentAttentionNotificationPayloadInput): AgentAttentionNotificationPayload;
+export {};
+//# sourceMappingURL=agent-attention-notification.d.ts.map

package/dist/agent-attention-notification.js

@@ -0,0 +1,140 @@
+const NOTIFICATION_PREVIEW_LIMIT = 220;
+const normalizeNotificationText = (text) => text.replace(/\s+/g, " ").trim();
+const truncateNotificationText = (text, limit) => {
+    if (text.length <= limit) {
+        return text;
+    }
+    const trimmed = text.slice(0, Math.max(0, limit - 3)).trimEnd();
+    return trimmed.length > 0 ? `${trimmed}...` : text.slice(0, limit);
+};
+const stripMarkdownToText = (markdown) => {
+    let text = markdown.replace(/\r\n/g, "\n");
+    // Strip fenced code markers but keep the code content itself.
+    text = text.replace(/^\s*```[^\n]*$/gm, "");
+    text = text.replace(/^\s*~~~[^\n]*$/gm, "");
+    // Markdown links/images.
+    text = text.replace(/!\[([^\]]*)\]\((?:[^()\\]|\\.)*\)/g, "$1");
+    text = text.replace(/\[([^\]]+)\]\((?:[^()\\]|\\.)*\)/g, "$1");
+    // Structural prefixes.
+    text = text.replace(/^\s{0,3}#{1,6}\s+/gm, "");
+    text = text.replace(/^\s{0,3}>+\s?/gm, "");
+    text = text.replace(/^\s{0,3}(?:[*+-]|\d+\.)\s+/gm, "");
+    text = text.replace(/^\s{0,3}(?:[-*_]\s*){3,}$/gm, "");
+    // Inline markdown markers.
+    text = text.replace(/`([^`]+)`/g, "$1");
+    text = text.replace(/\*\*([^*]+)\*\*/g, "$1");
+    text = text.replace(/__([^_]+)__/g, "$1");
+    text = text.replace(/\*([^*\n]+)\*/g, "$1");
+    text = text.replace(/_([^_\n]+)_/g, "$1");
+    text = text.replace(/~~([^~]+)~~/g, "$1");
+    // Angle-bracketed URL autolinks.
+    text = text.replace(/<([^>\n]+)>/g, "$1");
+    return text;
+};
+const buildNotificationPreview = (text) => {
+    if (!text) {
+        return null;
+    }
+    const normalized = normalizeNotificationText(stripMarkdownToText(text));
+    if (!normalized) {
+        return null;
+    }
+    return truncateNotificationText(normalized, NOTIFICATION_PREVIEW_LIMIT);
+};
+const safeStringify = (value) => {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return null;
+    }
+};
+const buildPermissionDetails = (request) => {
+    if (!request) {
+        return null;
+    }
+    const title = request.title?.trim();
+    const description = request.description?.trim();
+    const details = [];
+    if (title) {
+        details.push(title);
+    }
+    if (description && description !== title) {
+        details.push(description);
+    }
+    if (details.length > 0) {
+        return details.join(" - ");
+    }
+    const inputPreview = request.input ? safeStringify(request.input) : null;
+    if (inputPreview) {
+        return inputPreview;
+    }
+    const metadataPreview = request.metadata ? safeStringify(request.metadata) : null;
+    if (metadataPreview) {
+        return metadataPreview;
+    }
+    return request.name?.trim() || request.kind;
+};
+export function findLatestAssistantMessageFromTimeline(timeline) {
+    // Providers may stream assistant content in consecutive chunks.
+    const chunks = [];
+    for (let i = timeline.length - 1; i >= 0; i -= 1) {
+        const item = timeline[i];
+        if (item.type !== "assistant_message" || typeof item.text !== "string") {
+            if (chunks.length > 0) {
+                break;
+            }
+            continue;
+        }
+        chunks.push(item.text);
+    }
+    if (chunks.length === 0) {
+        return null;
+    }
+    return chunks.toReversed().join("");
+}
+export function findLatestPermissionRequest(pendingPermissions) {
+    let latest = null;
+    for (const request of pendingPermissions.values()) {
+        latest = request;
+    }
+    return latest;
+}
+function resolveAgentAttentionTitle(reason) {
+    if (reason === "permission")
+        return "Agent needs permission";
+    if (reason === "error")
+        return "Agent needs attention";
+    return "Agent finished";
+}
+function resolveAgentAttentionPreview(input) {
+    if (input.reason === "finished") {
+        return buildNotificationPreview(input.assistantMessage);
+    }
+    if (input.reason === "permission") {
+        return buildNotificationPreview(buildPermissionDetails(input.permissionRequest));
+    }
+    return null;
+}
+function resolveAgentAttentionFallbackBody(reason) {
+    if (reason === "permission")
+        return "Permission requested.";
+    if (reason === "error")
+        return "Encountered an error.";
+    return "Finished working.";
+}
+export function buildAgentAttentionNotificationPayload(input) {
+    const title = resolveAgentAttentionTitle(input.reason);
+    const preview = resolveAgentAttentionPreview(input);
+    const body = preview ?? resolveAgentAttentionFallbackBody(input.reason);
+    return {
+        title,
+        body,
+        data: {
+            serverId: input.serverId,
+            agentId: input.agentId,
+            reason: input.reason,
+        },
+    };
+}
+//# sourceMappingURL=agent-attention-notification.js.map

package/dist/agent-labels.d.ts

@@ -0,0 +1,2 @@
+export declare const PARENT_AGENT_ID_LABEL = "paseo.parent-agent-id";
+//# sourceMappingURL=agent-labels.d.ts.map

package/dist/agent-labels.js

@@ -0,0 +1,2 @@
+export const PARENT_AGENT_ID_LABEL = "paseo.parent-agent-id";
+//# sourceMappingURL=agent-labels.js.map

package/dist/agent-lifecycle.d.ts

@@ -0,0 +1,3 @@
+export declare const AGENT_LIFECYCLE_STATUSES: readonly ["initializing", "idle", "running", "error", "closed"];
+export type AgentLifecycleStatus = (typeof AGENT_LIFECYCLE_STATUSES)[number];
+//# sourceMappingURL=agent-lifecycle.d.ts.map

package/dist/agent-lifecycle.js

@@ -0,0 +1,8 @@
+export const AGENT_LIFECYCLE_STATUSES = [
+    "initializing",
+    "idle",
+    "running",
+    "error",
+    "closed",
+];
+//# sourceMappingURL=agent-lifecycle.js.map

package/dist/agent-state-bucket.d.ts

@@ -0,0 +1,13 @@
+import type { AgentLifecycleStatus } from "./agent-lifecycle.js";
+import type { WorkspaceStateBucket } from "./messages.js";
+export type AgentAttentionReason = "finished" | "error" | "permission" | null | undefined;
+export interface AgentStateBucketInput {
+    status: AgentLifecycleStatus;
+    pendingPermissionCount?: number;
+    requiresAttention?: boolean;
+    attentionReason?: AgentAttentionReason;
+}
+export declare function deriveAgentStateBucket(input: AgentStateBucketInput): WorkspaceStateBucket;
+export declare function getWorkspaceStateBucketPriority(bucket: WorkspaceStateBucket): number;
+export declare function getAgentStatusPriority(input: AgentStateBucketInput): number;
+//# sourceMappingURL=agent-state-bucket.d.ts.map

package/dist/agent-state-bucket.js

@@ -0,0 +1,41 @@
+const WORKSPACE_STATE_BUCKET_PRIORITY = {
+    needs_input: 0,
+    failed: 1,
+    running: 2,
+    attention: 3,
+    done: 4,
+};
+export function deriveAgentStateBucket(input) {
+    if ((input.pendingPermissionCount ?? 0) > 0 || input.attentionReason === "permission") {
+        return "needs_input";
+    }
+    if (input.status === "error" || input.attentionReason === "error") {
+        return "failed";
+    }
+    if (input.status === "running") {
+        return "running";
+    }
+    if (input.requiresAttention) {
+        return "attention";
+    }
+    return "done";
+}
+export function getWorkspaceStateBucketPriority(bucket) {
+    return WORKSPACE_STATE_BUCKET_PRIORITY[bucket];
+}
+export function getAgentStatusPriority(input) {
+    if ((input.pendingPermissionCount ?? 0) > 0 || input.attentionReason === "permission") {
+        return 0;
+    }
+    if (input.status === "error" || input.attentionReason === "error") {
+        return 1;
+    }
+    if (input.status === "running") {
+        return 2;
+    }
+    if (input.status === "initializing") {
+        return 3;
+    }
+    return 4;
+}
+//# sourceMappingURL=agent-state-bucket.js.map

package/dist/agent-title-limits.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_EXPLICIT_AGENT_TITLE_CHARS = 200;
+export declare const MAX_AUTO_AGENT_TITLE_CHARS = 40;
+//# sourceMappingURL=agent-title-limits.d.ts.map

package/dist/agent-title-limits.js

@@ -0,0 +1,3 @@
+export const MAX_EXPLICIT_AGENT_TITLE_CHARS = 200;
+export const MAX_AUTO_AGENT_TITLE_CHARS = 40;
+//# sourceMappingURL=agent-title-limits.js.map

package/dist/agent-types.d.ts

@@ -0,0 +1,421 @@
+import type { AgentAttachment } from "./messages.js";
+export type AgentProvider = string;
+export interface AgentMetadata {
+    [key: string]: unknown;
+}
+/**
+ * Stdio-based MCP server (spawns a subprocess).
+ */
+export interface McpStdioServerConfig {
+    type: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/**
+ * HTTP-based MCP server.
+ */
+export interface McpHttpServerConfig {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+}
+/**
+ * SSE-based MCP server (Server-Sent Events over HTTP).
+ */
+export interface McpSseServerConfig {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+}
+/**
+ * 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;
+    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;
+    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 {
+    supportsStreaming: boolean;
+    supportsSessionPersistence: 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;
+} | {
+    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