@aibolabs/plugin-protocol 0.1.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chldu2000
+
+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,15 @@
+# @aibolabs/plugin-protocol
+
+Aibo 公共 JSON 类型与呈现能力声明。零运行时依赖，不导出 Svelte、DOM、CSS、挂载句柄或函数回调。
+
+- `@aibolabs/plugin-protocol/semantic`：语义快照与动作。
+- `@aibolabs/plugin-protocol/presentation`：呈现代际消息；仍标记 experimental-v1。
+- `@aibolabs/plugin-protocol/renderer`：纯数据 renderer 描述、核心语义和支持版本常量。
+- 默认入口另导出 Capability Runtime 2.0 的初始化、调用、scope、结果及子请求目标类型。
+
+包版本不替代 wire schema 版本。当前语义数据类型保留 experimental-v1、v1 与 v1.1；具体载荷仍须通过宿主运行时 schema 校验，TypeScript 类型本身不是权限或有效性证明。
+
+安装：`npm install -D @aibolabs/plugin-protocol`。包版本等于宿主 SDK 版本；生成的包没有运行时或类型依赖。
+仓库内构建：从仓库根运行 `pnpm exec tsc -p packages/plugin-protocol/tsconfig.json`；发布见 `scripts/publish-sdk.mjs`。
+
+可执行 renderer 的 mount/update/dispose 接口继续属于可信宿主本地层，不从此包重导出。

package/dist/agent-icon.d.ts

@@ -0,0 +1,5 @@
+/** Monochrome SVG path in a 24 × 24 viewBox. No markup, URLs or styling. */
+export type AgentIcon = {
+    path: string;
+};
+export declare function readAgentIcon(value: unknown): AgentIcon | undefined;

package/dist/agent-icon.js

@@ -0,0 +1,10 @@
+export function readAgentIcon(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const icon = value;
+    if (Object.keys(icon).length !== 1 || typeof icon.path !== 'string')
+        return undefined;
+    if (icon.path.length > 8192 || !/^[Mm][0-9MmZzLlHhVvCcSsQqTtAaEe.,+\s-]+$/.test(icon.path))
+        return undefined;
+    return { path: icon.path };
+}

package/dist/capability.d.ts

@@ -0,0 +1,114 @@
+import type { AgentSettingsContext } from './settings.js';
+import type { JsonValue } from './semantic.js';
+export declare const CAPABILITY_RUNTIME_PROTOCOL = "2.0";
+/** Explicit opt-in for invocation streams and controls; 2.0 keeps its original meaning. */
+export declare const CAPABILITY_INTERACTIVE_PROTOCOL = "2.1";
+export type CapabilityScope = {
+    kind: 'application';
+} | {
+    kind: 'workspace' | 'session';
+    id: string;
+};
+export type CapabilityRequest = {
+    scope: CapabilityScope;
+    capability: string;
+    version: string;
+    requestId: string;
+    turnId?: string;
+    input: JsonValue;
+};
+export type CapabilityResult = {
+    instanceId: string;
+    invocationId: string;
+    installationId: string;
+    generationId: string;
+    output: JsonValue;
+};
+export type CapabilityFailure = {
+    code: string;
+    message: string;
+    invocationId: string | null;
+};
+export type CapabilityOperation = {
+    capability: string;
+    version: string;
+    operationId: string;
+};
+export type CapabilityInitialization = {
+    protocol: '2.0' | '2.1';
+    instanceId: string;
+    generationId: string;
+    installationId: string;
+    pluginId: string;
+    pluginVersion: string;
+    contributionId: string;
+    privateData: {
+        path: string;
+        formatVersion: 1;
+    };
+};
+export type CapabilityInvocation = {
+    invocationId: string;
+    instanceId: string;
+    generationId: string;
+    contributionId: string;
+    capability: string;
+    contractVersion: string;
+    operationId: string;
+    scope: CapabilityScope;
+    deadlineUnixMs: number;
+    context: {
+        hostTools?: {
+            schema: 'aibo.host-tools/v1';
+            tools: {
+                name: string;
+                description: string;
+                inputSchema: JsonValue;
+                outputSchema?: JsonValue;
+                annotations?: JsonValue;
+            }[];
+        };
+        settings?: AgentSettingsContext;
+        turnId: string | null;
+        workspaceId: string | null;
+        workspacePath: string | null;
+        originalCaller: {
+            kind: 'window';
+            id: string;
+        };
+        permissions: string[];
+        callChain: {
+            invocationId: string;
+            installationId: string;
+            contributionId: string;
+        }[];
+    };
+    input: JsonValue;
+};
+export type CapabilityCallTarget = {
+    pluginId: string;
+    contributionId: string;
+    capability: string;
+    version: string;
+    input: JsonValue;
+};
+/** Identity comes from the active invocation, never from an event producer. */
+export type CapabilityStreamEvent = {
+    instanceId: string;
+    generationId: string;
+    contributionId: string;
+    invocationId: string;
+    sequence: number;
+    event: JsonValue;
+};
+/** Host-authorized control of a running invocation; it cannot replace scope or permissions. */
+export type CapabilityControl = {
+    instanceId: string;
+    generationId: string;
+    contributionId: string;
+    invocationId: string;
+    capability: string;
+    contractVersion: string;
+    operationId: string;
+    input: JsonValue;
+};

package/dist/capability.js

@@ -0,0 +1,3 @@
+export const CAPABILITY_RUNTIME_PROTOCOL = '2.0';
+/** Explicit opt-in for invocation streams and controls; 2.0 keeps its original meaning. */
+export const CAPABILITY_INTERACTIVE_PROTOCOL = '2.1';

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export * from './semantic.js';
+export * from './presentation.js';
+export * from './renderer.js';
+export * from './capability.js';
+export * from './session.js';
+export * from './presentation-package.js';
+export * from './presentation-runtime.js';
+export * from './presentation-controls.js';
+export * from './agent-icon.js';
+export type { PresentationNavigation, PresentationNavigationAction, PresentationNavigationOperation } from './presentation-navigation.js';
+export type { PresentationConversation, PresentationConversationAction, PresentationConversationOperation } from './presentation-conversation.js';
+export type { PresentationGit, PresentationGitAction, PresentationGitDrafts } from './presentation-git.js';
+export type { PresentationInspector, PresentationInspectorAction, PresentationArtifactPreview, PresentationProjectEditor } from './presentation-inspector.js';
+export type { PresentationCapabilityWorkbench, PresentationCapabilityView, PresentationCapabilityAction, PresentationCapabilityContribution, PresentationCapabilityScope } from './presentation-capability.js';
+export type { PresentationLayout, PresentationLayoutAction } from './presentation-layout.js';
+export type { AgentSettingValue, AgentSettingField, AgentSettingsDescriptor, AgentSettingsTarget, AgentSettingsSnapshot, AgentSettingsSave, AgentSettingsContext } from './settings.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from './semantic.js';
+export * from './presentation.js';
+export * from './renderer.js';
+export * from './capability.js';
+export * from './session.js';
+export * from './presentation-package.js';
+export * from './presentation-runtime.js';
+export * from './presentation-controls.js';
+export * from './agent-icon.js';

package/dist/presentation-capability.d.ts

@@ -0,0 +1,37 @@
+import type { Snapshot } from './semantic.js';
+export type PresentationCapabilityContribution = {
+    scope?: 'application' | 'workspace' | 'session';
+    extensionPoint?: string;
+    visibility?: 'always' | 'workspaceSelected' | 'sessionSelected';
+    installationId: string;
+    contributionId: string;
+    title: string;
+    available: boolean;
+    issue: string | null;
+};
+export type PresentationCapabilityScope = {
+    kind: 'application';
+} | {
+    kind: 'workspace' | 'session';
+    id: string;
+};
+export type PresentationCapabilityView = {
+    snapshot: Snapshot | null;
+    error: string;
+    enhanced: boolean;
+    layout: 'central' | 'sidebar';
+    focusTarget: string | null;
+    restoring: boolean;
+};
+export type PresentationCapabilityWorkbench = {
+    catalog: PresentationCapabilityContribution[];
+    selected: PresentationCapabilityContribution | null;
+    scope: PresentationCapabilityScope;
+    view: PresentationCapabilityView;
+};
+export type PresentationCapabilityAction = {
+    token: string;
+    operation: 'open' | 'close' | 'reload' | 'toggleLayout' | 'toggleReading' | 'semantic';
+    event: 'click';
+    args: readonly (string | null)[];
+};

package/dist/presentation-capability.js

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

package/dist/presentation-controls.d.ts

@@ -0,0 +1,160 @@
+import type { AgentIcon } from './agent-icon.js';
+/** Data-only control customization contract; callbacks remain in the host UI kit. */
+export type PresentationModelCell = {
+    id: string;
+    label: string;
+    description: string | null;
+    available: boolean;
+    active: boolean;
+};
+export type PresentationModelColumn = Pick<PresentationModelCell, 'id' | 'label' | 'description'>;
+export type PresentationModelRow = {
+    reference: string;
+    label: string;
+    isDefault: boolean;
+    active: boolean;
+    defaultActive: boolean;
+    cells: readonly PresentationModelCell[];
+};
+export type PresentationModelMatrix = {
+    columns: readonly PresentationModelColumn[];
+    rows: readonly PresentationModelRow[];
+    defaultLabel: string;
+    defaultTitle: string;
+    fastTier: {
+        id: string;
+        label: string;
+        description: string | null;
+        active: boolean;
+    } | null;
+    disabled: boolean;
+};
+export type PresentationStatusMark = {
+    agent: 'codex' | 'pi' | 'plugin';
+    icon?: AgentIcon;
+    tone: 'idle' | 'running' | 'attention' | 'danger' | 'muted';
+    label: string;
+};
+/** Host API 1.1.0. The host supplies the label; decorative marks are hidden from assistive technology. */
+export type PresentationFileChangeMark = {
+    kind: 'added' | 'modified' | 'deleted' | 'renamed' | 'conflicted';
+    label: string;
+    decorative: boolean;
+};
+/** Host API 1.1.0. `appearance` is the host's classification of the declared policy; always decorative. */
+export type PresentationSessionControlMark = {
+    kind: 'permission' | 'mode';
+    profile: Readonly<Record<string, string | undefined>>;
+    compact: boolean;
+    appearance: {
+        icon: string;
+        tone: 'info' | 'plan' | 'write' | 'elevated' | 'neutral';
+    };
+};
+/** Host API 1.1.0. The package draws the closed trigger; `open` asks the host to draw the listbox outside the frame. */
+export type PresentationSelect = {
+    options: readonly {
+        value: string;
+        label: string;
+        disabled: boolean;
+    }[];
+    value: string;
+    placeholder: string;
+    disabled: boolean;
+    label: string;
+};
+/** Host API 1.1.0. Same trigger-only customization as Select. */
+export type PresentationModelContextSelect = {
+    options: readonly {
+        id: string;
+        label: string;
+        description: string | null;
+        tokens: number | null;
+    }[];
+    current: string | null;
+    disabled: boolean;
+};
+export type PresentationOpenAction = {
+    token: 'open';
+    kind: 'open';
+};
+/** Host API 1.1.0. File names only: host paths and image previews never reach the package. */
+export type PresentationAttachmentList = {
+    items: readonly {
+        id: string;
+        name: string;
+        mediaType: string;
+        sizeLabel: string | null;
+    }[];
+    removable: boolean;
+    disabled: boolean;
+    label: string;
+};
+/** Host API 1.1.0. Expanding long objectives is local package state. */
+export type PresentationGoalBar = {
+    objective: string;
+    statusLabel: string;
+    usageLabel: string | null;
+    busy: boolean;
+};
+/** Host API 1.1.0. `open` shows the host-owned subagent dialog. */
+export type PresentationSubagentCard = {
+    name: string;
+    task: string;
+    statusLabel: string;
+    activity: string;
+    failed: boolean;
+};
+export type PresentationControlData = {
+    control: 'ModelMatrix';
+    props: PresentationModelMatrix;
+    actions: readonly ({
+        token: string;
+        kind: 'model';
+        model: string;
+        reasoningEffort: string | null;
+    } | {
+        token: string;
+        kind: 'serviceTier';
+        serviceTier: string;
+    })[];
+} | {
+    control: 'AgentStatusMark';
+    props: PresentationStatusMark;
+    actions: readonly [];
+} | {
+    control: 'FileChangeMark';
+    props: PresentationFileChangeMark;
+    actions: readonly [];
+} | {
+    control: 'SessionControlMark';
+    props: PresentationSessionControlMark;
+    actions: readonly [];
+} | {
+    control: 'Select';
+    props: PresentationSelect;
+    actions: readonly PresentationOpenAction[];
+} | {
+    control: 'ModelContextSelect';
+    props: PresentationModelContextSelect;
+    actions: readonly PresentationOpenAction[];
+} | {
+    control: 'AttachmentList';
+    props: PresentationAttachmentList;
+    actions: readonly {
+        token: string;
+        kind: 'remove';
+        id: string;
+    }[];
+} | {
+    control: 'GoalBar';
+    props: PresentationGoalBar;
+    actions: readonly {
+        token: 'pause' | 'resume' | 'clear';
+        kind: 'pause' | 'resume' | 'clear';
+    }[];
+} | {
+    control: 'SubagentCard';
+    props: PresentationSubagentCard;
+    actions: readonly PresentationOpenAction[];
+};

package/dist/presentation-controls.js

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

package/dist/presentation-conversation.d.ts

@@ -0,0 +1,281 @@
+import type { SessionControl } from './session.js';
+type InteractionMode = 'ask' | 'plan' | 'edit';
+type ApprovalPolicy = 'never' | 'untrusted' | 'on-request' | 'trusted';
+type ApprovalReviewer = 'user' | 'auto-review' | 'none';
+type FilesystemPolicy = 'read-only' | 'workspace-write' | 'danger-full-access';
+type CommandPolicy = 'disabled' | 'approved' | 'trusted';
+type NetworkPolicy = 'disabled' | 'agent-managed';
+interface ExecutionProfile {
+    schema: 'aibo.execution-profile/v1';
+    interactionMode: InteractionMode;
+    approvalPolicy: ApprovalPolicy;
+    approvalReviewer: ApprovalReviewer;
+    filesystemPolicy: FilesystemPolicy;
+    commandPolicy: CommandPolicy;
+    networkPolicy: NetworkPolicy;
+    model?: string | null;
+    reasoningEffort?: string | null;
+}
+interface ResolvedExecutionProfile {
+    schema: 'aibo.execution-profile/v1';
+    requested: ExecutionProfile;
+    enforced: ExecutionProfile;
+    unsupported: string[];
+    adapterCapabilities: string[];
+    nativeSandbox: boolean;
+    sessionControls?: SessionControl[];
+    resolvedAt: string;
+}
+interface SessionExecutionProfile extends ResolvedExecutionProfile {
+    sessionId: string;
+}
+type SessionState = 'created' | 'starting' | 'idle' | 'running' | 'waiting_approval' | 'waiting_user' | 'compacting' | 'interrupted' | 'failed' | 'closed';
+interface Session {
+    id: string;
+    workspaceId: string;
+    agent: string;
+    label: string;
+    state: SessionState;
+    archived: boolean;
+    historyOnly?: boolean;
+    externalSessionId: string | null;
+    pluginInstallationId: string | null;
+    capabilities: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface SessionModelOption {
+    reference: string;
+    label: string;
+    provider: string | null;
+    id: string;
+    description: string | null;
+    isDefault: boolean;
+    defaultReasoningEffort: string | null;
+    reasoningEfforts: SessionReasoningOption[];
+    serviceTiers: SessionServiceTierOption[];
+    contextWindows?: SessionContextWindowOption[];
+}
+interface SessionReasoningOption {
+    id: string;
+    label: string;
+    description: string | null;
+}
+interface SessionContextWindowOption {
+    id: string;
+    label: string;
+    description: string | null;
+    tokens?: number | null;
+}
+interface SessionServiceTierOption {
+    id: string;
+    label: string;
+    description: string | null;
+}
+interface SessionModelCatalog {
+    parameterScope?: 'all-models' | 'current-model';
+    current: SessionModelOption | null;
+    models: SessionModelOption[];
+    currentReasoningEffort: string | null;
+    reasoningEfforts: SessionReasoningOption[];
+    currentServiceTier: string | null;
+    currentContextWindow?: string | null;
+}
+interface AgentGoal {
+    objective: string;
+    status: 'active' | 'paused' | 'completed' | 'cleared' | 'blocked' | 'usageLimited' | 'budgetLimited' | 'unknown';
+    tokenBudget: number | null;
+    tokensUsed: number | null;
+    timeUsedSeconds?: number | null;
+    updatedAt: string | null;
+}
+interface WorkspacePathSuggestion {
+    path: string;
+    isDirectory: boolean;
+}
+type AgentCommandCategory = 'agent' | 'skill' | 'extension';
+type AgentCommandExecution = 'aibo' | 'adapter' | 'prompt';
+interface AgentCommand {
+    insertionText?: string;
+    id?: string;
+    name: string;
+    aliases?: string[];
+    description: string | null;
+    source: 'extension' | 'prompt' | 'skill' | string;
+    category?: AgentCommandCategory;
+    execution?: AgentCommandExecution;
+    /** Legacy display metadata; binding determines command ownership. */
+    agent?: string;
+    enabled?: boolean;
+    argumentHint?: string;
+    capability?: string;
+}
+interface ContextAttachment {
+    schema: 'aibo.context-attachment/v1';
+    id: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string | null;
+    path: string;
+    contentHash: string | null;
+    size: number | null;
+    mediaType: string;
+    source: 'picker' | 'drop' | 'manual' | string;
+    sendStrategy: 'reference' | 'inline' | string;
+    inlineContext?: string | null;
+    createdAt: string;
+}
+interface UserInputOption {
+    label: string;
+    description: string | null;
+}
+interface UserInputQuestion {
+    id: string;
+    header: string | null;
+    question: string;
+    options: UserInputOption[];
+    isOther: boolean;
+}
+interface UserInputRequest {
+    requestId: string;
+    sessionId: string;
+    turnId: string | null;
+    questions: UserInputQuestion[];
+    isBlocking: boolean;
+}
+interface ApprovalOption {
+    id: string;
+    kind: 'allow' | 'reject';
+    label: string | null;
+}
+/** A pending Agent approval of the selected session; the host revalidates every submitted choice. */
+interface ApprovalRequest {
+    requestId: string;
+    sessionId: string;
+    turnId: string | null;
+    kind: string;
+    command: string | null;
+    cwd: string | null;
+    availableDecisions: ('accept' | 'cancel')[];
+    /** Empty for providers answering by decision. */
+    options: ApprovalOption[];
+}
+interface QueuedMessage {
+    id: string;
+    text: string;
+    status: 'pending' | 'sending' | 'failed' | 'uncertain';
+    error: string | null;
+    createdAt: string;
+}
+interface AgentQueueSnapshot {
+    items?: QueuedMessage[];
+    paused?: boolean;
+    revision?: number;
+    sessionId: string;
+    steering: string[];
+    followUp: string[];
+    updatedAt: string;
+}
+interface PiSessionTreeNode {
+    id: string;
+    parentId: string | null;
+    type: string;
+    timestamp: string;
+    role?: string;
+    summary?: string;
+    label?: string;
+    children: PiSessionTreeNode[];
+}
+interface PiSessionTreeSnapshot {
+    sessionId: string;
+    externalSessionId: string | null;
+    leafId: string | null;
+    tree: PiSessionTreeNode[];
+}
+/** Complete host conversation data, independent of framework and native APIs. */
+export type PresentationConversation = {
+    workspace: {
+        id: string;
+        label: string;
+        path: string;
+        trust: string;
+    } | null;
+    session: Session | null;
+    goal: AgentGoal | null;
+    goalBusy?: boolean;
+    thread: {
+        id: string;
+        turnCount: number | null;
+    } | null;
+    timeline: {
+        id: string;
+        turnId: string | null;
+        role: string;
+        toolName: string | null;
+        entryType: string | null;
+        content: string;
+        status: string;
+    }[];
+    timelineVisibleCount: number;
+    /** Group ordinary system events; summaries and reasoning always remain separate. */
+    groupSystemItems?: boolean;
+    usage: {
+        input: number | null;
+        output: number | null;
+        total: number | null;
+        contextUsed: number | null;
+        contextLimit: number | null;
+        contextEstimated: boolean;
+        plan?: string | null;
+        limits?: {
+            id: string;
+            label: string | null;
+            usedPercent: number;
+            windowMinutes: number | null;
+            resetsAt: number | null;
+        }[];
+        credits?: {
+            balance: string | null;
+            unlimited: boolean;
+        } | null;
+    } | null;
+    retryPrompt: string | null;
+    retryReason: string | null;
+    userInputRequests: UserInputRequest[];
+    approvalRequests: ApprovalRequest[];
+    answerDrafts: Record<string, string>;
+    queue: AgentQueueSnapshot | null;
+    activityLabel: string | null;
+    compacting: boolean;
+    running: boolean;
+    archiving: boolean;
+    busy: boolean;
+    attachments: ContextAttachment[];
+    executionProfile: SessionExecutionProfile | null;
+    modelConfiguration: {
+        currentReasoningEffort: string | null;
+        selectedReasoningEffort: string | null;
+        defaultAction: 'preserve' | 'reset';
+    };
+    modelCatalog: SessionModelCatalog | null;
+    modelCatalogLoading: boolean;
+    modelOverride: string | null;
+    workspacePathSuggestions: WorkspacePathSuggestion[];
+    sessionSuggestions?: Session[];
+    agentCommands: AgentCommand[];
+    agentCommandsLoading: boolean;
+    draft: string;
+    draftFailed: boolean;
+    tree: PiSessionTreeSnapshot | null;
+    treeOpen: boolean;
+    treeNavigationStatus: string | null;
+};
+export type PresentationConversationOperation = 'copyCode' | 'openLink' | 'draft' | 'send' | 'stop' | 'retry' | 'queueSteer' | 'queueFollowUp' | 'clearQueue' | 'removeQueuedMessage' | 'sendQueuedMessage' | 'resumeQueue' | 'clearGoal' | 'pauseGoal' | 'resumeGoal' | 'addAttachments' | 'addDirectory' | 'removeAttachment' | 'selectPath' | 'selectSessionReference' | 'selectCommand' | 'openSubagent' | 'loadOlder' | 'fork' | 'loadModels' | 'selectModel' | 'selectServiceTier' | 'selectContextWindow' | 'selectAccess' | 'compact' | 'answer' | 'chooseAnswer' | 'submitAnswers' | 'cancelAnswers' | 'resolveApproval' | 'openTree' | 'closeTree' | 'refreshTree' | 'selectTreeNode';
+export type PresentationConversationAction = {
+    token: string;
+    operation: PresentationConversationOperation;
+    event: 'click' | 'input' | 'change';
+    /** Fixed semantic arguments chosen by the host, not parameters supplied by package code. */
+    args: readonly (string | null)[];
+};
+export {};

package/dist/presentation-conversation.js

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