@ycodium-ai/plugin-api 0.2.2936 → 0.2.2942

package/README.md

@@ -56,7 +56,7 @@ import { definePlugin } from "@ycodium-ai/plugin-api";
 
 export default definePlugin({
   id: "my-plugin",
-  apiVersion: 3,
+  apiVersion: 4,
   activate: (ctx) => {
     ctx.log.info("hello");
 
@@ -158,6 +158,14 @@ your tool returns must stand on its own. To show an image your tool wrote into t
 call `bridge.useWorkspaceFileUrl({ environmentId, threadId, path })` after checking the
 `workspaceFileUrl` capability. Mobile shows the text result.
 
+## Experimental seats
+
+`project.workbench.tab` and `sidebar.project.actions` render on Web and Desktop.
+Mobile loads a plugin that registers them and does not draw the seats. The props,
+when the host refreshes them, and what happens when a tab throws are experimental.
+Do not treat that shape as a stable contract. It will be fixed when the first real
+plugin depends on it.
+
 ## Permissions
 
 Anything that reaches outside the plugin is declared in `ycodium.permissions` and shown to
@@ -179,9 +187,17 @@ A plugin can ship skills for the agents. List directories inside your package un
 ```
 
 While the plugin is enabled, each skill is installed for every supported agent as
-`ycodium-<name>`, and removed again when the plugin is disabled or uninstalled. Only
-`SKILL.md` is copied: if the skill needs a script or a program, expose it as one of your
-tools and tell the agent to call that tool. A user's own skill with the same name wins.
+`ycodium-<name>`, and removed again when the plugin is disabled or uninstalled. A user's
+own skill with the same name wins. To ship a script or other file next to `SKILL.md`,
+declare that relative subtree:
+
+```json
+"skills": [{ "dir": "./skills/report-writer", "files": ["scripts/render.sh"] }]
+```
+
+Those files are copied into the session skill directory. A path with `..`, a file outside
+the skill directory, or a file over the size cap fails the plugin load. A settings skill
+with the same name still wins, and then these extra files are not copied.
 
 ## File previews
 
@@ -214,12 +230,24 @@ shows up there without anyone registering it.
 
 ## THERE WILL BE COMPATIBILITY-BREAKING CHANGES
 
-The definition's `apiVersion` is checked for **exact equality**. Declare the version your
-plugin targets as a literal; do not read the host's `PLUGIN_API_VERSION` to make the declaration
-automatically match. The current API is 3. Plugins targeting API 1 or 2 are refused before
-activation; the message names the version the plugin declared and the one this Ycodium loads,
-and the plugin card offers an update. Update plugins against the current types and republish;
-there is no compatibility layer.
+The definition's `apiVersion` is a closed window: the host loads 3 and 4, and refuses every other
+value. Declare the version your plugin targets as a literal; do not read the host's
+`PLUGIN_API_VERSION` to make the declaration automatically match. The current API is 4. Plugins
+that still declare 3 continue to load. Plugins targeting API 1 or 2 are refused before activation;
+the message names the version the plugin declared and the ones this Ycodium loads, and the plugin
+card offers an update. A plugin that declares a version newer than 4 is refused until Ycodium
+itself is updated, with no update button.
+
+### API 4
+
+API 4 adds types and permission kinds for system-prompt sections, tool guards, presentation
+payloads, extra conversation seats, session projections, agent presets, workspace writes,
+and user-thread commands. The host still loads a plugin that declares 3. The host wires those
+context fields: prompt text is prefixed onto a turn, guards run before a tool executes, seats
+and presentation render, session projections persist, and workspace writes during a tool call
+run when declared. Interactive terminals, directory-period write roots, and installing other
+plugins from a plugin were removed before this API shipped. A host build from before this
+wiring still rejects the new methods with `not-implemented`.
 
 ### API 3
 

package/dist/capabilityPorts.d.ts

@@ -0,0 +1,136 @@
+/**
+ * ADR-0036 能力口的类型。
+ *
+ * 约束：未声明的调用拒绝 `reason: "undeclared"`。
+ * 提示注入、守卫、投影落库、预设列表、座位绘制、调用期写盘由宿主接线。
+ * 写盘只有工具调用期的 `invocation.workspace`，没有目录期根。
+ * 插件不经 `ctx` 安装或卸载别的插件。
+ *
+ * @module @ycodium-ai/plugin-api/capabilityPorts
+ */
+import type { PluginDisposer } from "./index.ts";
+/** 单份工具展示体上限（ADR-0036）。不进入模型可见的 `text`。 */
+export declare const MAX_PLUGIN_TOOL_PRESENTATION_BYTES: number;
+/** 单份会话投影上限。不是编排事件。 */
+export declare const MAX_PLUGIN_SESSION_PROJECTION_BYTES: number;
+/**
+ * 宿主挂在插件命令表上的流名字。客户端用现有 `plugins.subscribe` 订，
+ * payload 是 `{ name, threadId }`，每条值是 `{ present, value }`。
+ */
+export declare const PLUGIN_SESSION_PROJECTION_COMMAND = "ycodium.sessionProjection";
+/** 单文件写入上限。本权限不含删除。 */
+export declare const MAX_PLUGIN_WORKSPACE_WRITE_BYTES: number;
+/**
+ * 技能伴随文件上限。ADR 要求超限即 resolve 失败，但没给数字。
+ * 这是 Phase 1 宿主占位；Phase 2 拷进会话 skill 目录时必须遵守同一对数字。
+ */
+export declare const MAX_PLUGIN_SKILL_COMPANION_FILE_BYTES: number;
+export declare const MAX_PLUGIN_SKILL_COMPANION_TOTAL_BYTES: number;
+/** JSON 值。宿主拒绝函数、bigint、循环引用和 `undefined`。 */
+export type PluginJson = null | boolean | number | string | readonly PluginJson[] | {
+    readonly [key: string]: PluginJson | undefined;
+};
+/** UTF-8 字节数。不是 JSON 的值抛 TypeError。 */
+export declare const pluginJsonByteLength: (value: unknown) => number;
+/**
+ * 收下工具展示体。缺席、非 JSON、或超过 {@link MAX_PLUGIN_TOOL_PRESENTATION_BYTES} 时返回 null。
+ * 调用方仍画文字卡，并且不得把这份值写进模型可见文本。
+ */
+export declare const acceptPluginToolPresentation: (value: unknown) => PluginJson | null;
+/**
+ * 工具结果上的展示体。可选，缺席时仍画文字卡。
+ * Phase 2 必须按调用 id 回取，并且不得把这份值拼进模型可见文本或活动快照截断。
+ */
+export interface PluginToolPresentation {
+    readonly presentation?: PluginJson | undefined;
+}
+/**
+ * 与 tool view 共用的调用 id。Phase 1 可选，以免旧 fixture 深比较失败。
+ * Phase 2 每次工具调用都必须填写。
+ */
+export interface PluginToolInvocationIdentity {
+    readonly id?: string | undefined;
+}
+/**
+ * `workspace.write` 的调用期写。没有删除。
+ * 只在 handler 返回前可用；根是这次 `invocation.workspace` 的根。
+ */
+export interface PluginInvocationWorkspaceWrite {
+    writeFile?(path: string, bytes: Uint8Array): Promise<void>;
+    mkdir?(path: string): Promise<void>;
+}
+export interface PluginSystemPromptSection {
+    readonly id: string;
+    readonly text: string;
+    /** 只在这条会话的 preset 是这个 id 时拼进本轮提示。缺省则每条会话都带。 */
+    readonly whenPresetId?: string;
+}
+export interface PluginSystemPromptTurn {
+    readonly threadId: string;
+    readonly turnId: string | null;
+    /** 这条会话当前的 preset。没选时为 null。旧调用方可以不填。 */
+    readonly presetId?: string | null;
+}
+/**
+ * 需要 `systemPrompt`。宿主把正文加在每一家 driver 的本轮用户消息前。
+ * 插件不按 driver 各写一条。
+ */
+export interface PluginSystemPrompt {
+    section(input: PluginSystemPromptSection): PluginDisposer;
+    context(provide: (turn: PluginSystemPromptTurn) => string | null | Promise<string | null>): PluginDisposer;
+}
+export type PluginToolGuardDecision = {
+    readonly decision: "allow";
+} | {
+    readonly decision: "deny";
+    readonly reason: string;
+};
+export interface PluginToolGuardInput {
+    readonly name: string;
+    readonly args: PluginJson;
+    readonly threadId: string | null;
+}
+/**
+ * 需要 `tools.guard`。没有 `register`。守卫不替换实现，也不改参数。
+ * 宿主按注册顺序在工具执行前调用，拒绝优先。
+ */
+export interface PluginTools {
+    guard(guard: (input: PluginToolGuardInput) => PluginToolGuardDecision | Promise<PluginToolGuardDecision>): PluginDisposer;
+}
+export interface PluginSessionProjectionName {
+    readonly name: string;
+}
+export interface PluginSessionProjectionValue extends PluginSessionProjectionName {
+    readonly threadId: string;
+    readonly value: PluginJson;
+}
+/**
+ * 需要 `sessionProjection`。`register` 返回现有 disposer。
+ * `set` 执行 1 MiB 上限，并按（插件，线程，名字）留下最新一份。
+ * 客户端用 `PLUGIN_SESSION_PROJECTION_COMMAND` 订阅。
+ */
+export interface PluginSessionProjections {
+    register(input: PluginSessionProjectionName): PluginDisposer;
+    set(input: PluginSessionProjectionValue): Promise<void>;
+}
+export interface PluginAgentPresetRegistration {
+    readonly id: string;
+    readonly displayName: string;
+    readonly description?: string | undefined;
+    readonly promptPrefix?: string | undefined;
+}
+/**
+ * 需要 `agentPresets`。只在该线程第一轮之前可选。
+ * 正文要进模型输入必须另声明 `systemPrompt`，不自建第二条提示通道。
+ */
+export interface PluginAgentPresets {
+    register(input: PluginAgentPresetRegistration): PluginDisposer;
+}
+/** `PluginContext` 在 Phase 1 增加的成员。字段名必须出现在插件 API 参考里。 */
+export interface PluginCapabilityContext {
+    readonly systemPrompt: PluginSystemPrompt;
+    readonly tools: PluginTools;
+    readonly sessionProjections: PluginSessionProjections;
+    readonly agentPresets: PluginAgentPresets;
+}
+//# sourceMappingURL=capabilityPorts.d.ts.map

package/dist/capabilityPorts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilityPorts.d.ts","sourceRoot":"","sources":["../src/capabilityPorts.ts"],"names":[],"mappings":"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"}

package/dist/capabilityPorts.js

@@ -0,0 +1,48 @@
+/** 单份工具展示体上限（ADR-0036）。不进入模型可见的 `text`。 */
+export const MAX_PLUGIN_TOOL_PRESENTATION_BYTES = 1024 * 1024;
+/** 单份会话投影上限。不是编排事件。 */
+export const MAX_PLUGIN_SESSION_PROJECTION_BYTES = 1024 * 1024;
+/**
+ * 宿主挂在插件命令表上的流名字。客户端用现有 `plugins.subscribe` 订，
+ * payload 是 `{ name, threadId }`，每条值是 `{ present, value }`。
+ */
+export const PLUGIN_SESSION_PROJECTION_COMMAND = "ycodium.sessionProjection";
+/** 单文件写入上限。本权限不含删除。 */
+export const MAX_PLUGIN_WORKSPACE_WRITE_BYTES = 20 * 1024 * 1024;
+/**
+ * 技能伴随文件上限。ADR 要求超限即 resolve 失败，但没给数字。
+ * 这是 Phase 1 宿主占位；Phase 2 拷进会话 skill 目录时必须遵守同一对数字。
+ */
+export const MAX_PLUGIN_SKILL_COMPANION_FILE_BYTES = 1024 * 1024;
+export const MAX_PLUGIN_SKILL_COMPANION_TOTAL_BYTES = 8 * 1024 * 1024;
+/** UTF-8 字节数。不是 JSON 的值抛 TypeError。 */
+export const pluginJsonByteLength = (value) => {
+    const encoded = JSON.stringify(value);
+    if (typeof encoded !== "string") {
+        throw new TypeError("value is not JSON");
+    }
+    return new TextEncoder().encode(encoded).byteLength;
+};
+/**
+ * 收下工具展示体。缺席、非 JSON、或超过 {@link MAX_PLUGIN_TOOL_PRESENTATION_BYTES} 时返回 null。
+ * 调用方仍画文字卡，并且不得把这份值写进模型可见文本。
+ */
+export const acceptPluginToolPresentation = (value) => {
+    if (value === undefined)
+        return null;
+    let encoded;
+    try {
+        const json = JSON.stringify(value);
+        if (typeof json !== "string")
+            return null;
+        encoded = json;
+    }
+    catch {
+        return null;
+    }
+    if (new TextEncoder().encode(encoded).byteLength > MAX_PLUGIN_TOOL_PRESENTATION_BYTES) {
+        return null;
+    }
+    return JSON.parse(encoded);
+};
+//# sourceMappingURL=capabilityPorts.js.map

package/dist/capabilityPorts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilityPorts.js","sourceRoot":"","sources":["../src/capabilityPorts.ts"],"names":[],"mappings":"AAYA,2CAA2C;AAC3C,MAAM,CAAC,MAAM,kCAAkC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE9D,uBAAuB;AACvB,MAAM,CAAC,MAAM,mCAAmC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/D;;;GAGG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,2BAA2B,CAAC;AAE7E,uBAAuB;AACvB,MAAM,CAAC,MAAM,gCAAgC,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAEjE;;;GAGG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAG,IAAI,GAAG,IAAI,CAAC;AACjE,MAAM,CAAC,MAAM,sCAAsC,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAWtE,uCAAuC;AACvC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,KAAc,EAAU,EAAE;IAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,mBAAmB,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC;AACtD,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,KAAc,EAAqB,EAAE;IAChF,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1C,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,UAAU,GAAG,kCAAkC,EAAE,CAAC;QACtF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAe,CAAC;AAC3C,CAAC,CAAC"}

package/dist/conversation.d.ts

@@ -26,6 +26,7 @@
  * @module @ycodium-ai/plugin-api/conversation
  */
 import type { ConversationComposerAccountUsage } from "./account-usage.ts";
+import type { ConversationPresetApi } from "./conversationPresets.ts";
 import type { ConversationAttachmentDocumentOpen, ConversationAttachmentsApi, ConversationMessageAttachment, ConversationPastedTextSource } from "./conversationAttachments.ts";
 export type * from "./conversationAttachments.ts";
 import type { ConversationAssistantQuoteApi, ConversationMessageLinkText, ConversationThreadReferenceApi } from "./conversationMessageLinks.ts";
@@ -38,6 +39,8 @@ export type * from "./conversationSkills.ts";
 import type { ConversationCommunicationRecord, ConversationTrajectoryRow } from "./conversationTrajectory.ts";
 export type * from "./conversationTrajectory.ts";
 import type { ConversationQueuedMessageEdit, ConversationQueueEntry, ConversationPendingQueueSubmission, ConversationQueueState } from "./conversation-queue.ts";
+import type { ConversationWorkEntry } from "./conversationWorkEntry.ts";
+export type * from "./conversationWorkEntry.ts";
 export type { AccountUsageCapability, AccountUsageCredentialIdentity, AccountUsageMetric, AccountUsageMetricKind, AccountUsageRefreshOutcome, AccountUsageRefreshResult, AccountUsageResetOutcome, AccountUsageScopeKind, AccountUsageSnapshot, AccountUsageUnit, ConversationComposerAccountUsage, } from "./account-usage.ts";
 /** 时间线派生输入。插件只透传，不解读。 */
 export type ConversationTimelineEntry = unknown;
@@ -96,57 +99,6 @@ export interface ConversationTurnUsage {
      */
     readonly cacheDisjoint?: boolean | undefined;
 }
-/** 工具/过程行的可渲染子集。展开详情走 `renderWorkGroup` 接缝，不在这里。 */
-export interface ConversationWorkEntry {
-    readonly id: string;
-    readonly createdAt: string;
-    readonly label: string;
-    readonly tone: "thinking" | "tool" | "info" | "error";
-    readonly detail?: string | undefined;
-    readonly command?: string | undefined;
-    readonly rawCommand?: string | undefined;
-    readonly changedFiles?: ReadonlyArray<string> | undefined;
-    readonly toolTitle?: string | undefined;
-    /** 分段标题（工具名/路径/参数摘要）；拿不到时宿主不给。 */
-    readonly toolLabel?: {
-        readonly name: string;
-        readonly path?: string | undefined;
-        readonly detail?: string | undefined;
-        readonly diffStat?: {
-            readonly additions: number;
-            readonly deletions: number;
-        } | undefined;
-        readonly descriptive: boolean;
-    } | undefined;
-    /** 工具的原始载荷（对插件不透明；折叠摘要的回退标题从里面猜工具名）。 */
-    readonly toolData?: unknown;
-    /**
-     * 出现即表示这是 Ycodium 自己的浏览器工具行；`pageUrl` 只在 agent 真的打开过那个页面时才有。
-     * 旧宿主不给这个字段，插件照旧画原来的图标。
-     */
-    readonly toolIcon?: {
-        readonly kind: "website";
-        readonly pageUrl?: string | undefined;
-    } | undefined;
-    readonly toolCallId?: string | undefined;
-    readonly turnId?: string | null | undefined;
-    readonly itemType?: string | undefined;
-    readonly toolLifecycleStatus?: string | undefined;
-    readonly sourceActivityKind?: string | undefined;
-    readonly taskId?: string | undefined;
-    readonly agentRole?: string | undefined;
-    readonly agentSpawn?: {
-        readonly workflowId: string | null;
-        readonly agentTaskIds: ReadonlyArray<string>;
-    } | undefined;
-    readonly childThread?: {
-        readonly childThreadId: string;
-        readonly title: string;
-        readonly instanceId: string | null;
-        readonly model: string | null;
-    } | undefined;
-    readonly backgroundTasks?: readonly ConversationWorkEntry[] | undefined;
-}
 /** 建议计划卡片（宿主 `ProposedPlan` 的结构子集）。 */
 export interface ConversationProposedPlan {
     readonly id: string;
@@ -953,9 +905,7 @@ export interface ConversationComposerApi {
         useActiveEnvironmentId(): ConversationEnvironmentId | null;
     };
     /** thread preset 列表（宿主 serverEnvironment 查询封装）。 */
-    readonly presets: {
-        useThreadPresets(environmentId: ConversationEnvironmentId | null): ReadonlyArray<ConversationThreadPreset>;
-    };
+    readonly presets: ConversationPresetApi;
     /** 同屏会话仲裁（宿主 useChatPaneKeydown / chatPaneVisibility）。 */
     readonly pane: {
         useKeydown(onKeydown: (event: KeyboardEvent) => void, options?: {
@@ -1671,7 +1621,7 @@ export interface ConversationComposerPlan {
         readonly status: "pending" | "inProgress" | "completed";
     }[] | null;
 }
-export type ConversationViewMode = "chat" | "trajectory";
+export type ConversationViewMode = "chat" | "trajectory" | "map";
 /** 会话身份与多 pane 仲裁。`active` 为 false 的实例不得绑定全局监听。 */
 export interface ConversationScopeProps {
     readonly environmentId: string;