@agent-phonon/protocol 0.2.0

package/dist/schemas/discovery.d.ts.map

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

package/dist/schemas/discovery.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { AgentId, Timestamp } from "./common.js";
+import { AgentCapabilities } from "./capabilities.js";
+/**
+ * Agent / 模型发现（design §5 / D14）。
+ *
+ * 发现 = 内部扫描机制（非协议）+ 对外暴露接口（属协议）。本文件只定义
+ * **对外接口**的数据形状：服务端借此感知「这台设备上哪些 agent 可用、
+ * 各自哪些模型可用」。
+ */
+/** 单个模型的可用性描述。 */
+export const ModelInfo = z.object({
+    /** 模型 id，session.create 的 `model` 入参取自这里。 */
+    id: z.string().min(1),
+    /** 展示名（可选）。 */
+    displayName: z.string().optional(),
+    /** 上下文窗口（token，若已知）。注意：以 phonon 实测/配置为准，不盲信后端返回。 */
+    contextWindow: z.number().int().positive().optional(),
+    /** 该模型当前是否可用（如鉴权过期会变 false）。 */
+    available: z.boolean().default(true),
+});
+/** 单个 agent 的发现条目。 */
+export const AgentDescriptor = z.object({
+    agentId: AgentId,
+    /** 展示名，如 "Claude Code" / "OpenClaw"。 */
+    displayName: z.string().min(1),
+    /** 适配器内部名，如 "openclaw" / "claude-code"。 */
+    adapter: z.string().min(1),
+    /** 整体是否可用（已安装 + 可执行 + 凭证就绪）。 */
+    available: z.boolean(),
+    /** 不可用时的原因（如 "not_installed" / "not_logged_in" / "no_credentials"）。 */
+    unavailableReason: z.string().optional(),
+    /** agent 自身版本（若可探测）。 */
+    version: z.string().optional(),
+    /** 可用模型列表。 */
+    models: z.array(ModelInfo),
+    /** 能力声明（随 discovery 暴露，见 §7）。 */
+    capabilities: AgentCapabilities,
+    /** 最近一次扫描时间。 */
+    scannedAt: Timestamp.optional(),
+});
+// --- discovery.list ---
+export const DiscoveryListParams = z.object({
+    /** 可选：只看可用的。 */
+    availableOnly: z.boolean().optional(),
+});
+export const DiscoveryListResult = z.object({
+    agents: z.array(AgentDescriptor),
+});
+// --- discovery.get ---
+export const DiscoveryGetParams = z.object({
+    agentId: AgentId,
+});
+export const DiscoveryGetResult = z.object({
+    agent: AgentDescriptor,
+});
+// --- discovery.changed (phonon -> server 主动推送，notification) ---
+export const DiscoveryChangedParams = z.object({
+    /** 变更类型：agent 上/下线、模型增减、能力变化。 */
+    kind: z.enum(["agent_added", "agent_removed", "agent_updated", "models_changed"]),
+    agentId: AgentId,
+    /** 变更后的完整快照（可选，便于服务端直接更新缓存）。 */
+    snapshot: AgentDescriptor.optional(),
+    at: Timestamp,
+});
+//# sourceMappingURL=discovery.js.map

package/dist/schemas/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/schemas/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;GAMG;AAEH,kBAAkB;AAClB,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,6CAA6C;IAC7C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,eAAe;IACf,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,oDAAoD;IACpD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACrD,gCAAgC;IAChC,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CACrC,CAAC,CAAC;AAGH,sBAAsB;AACtB,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,OAAO,EAAE,OAAO;IAChB,wCAAwC;IACxC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,2CAA2C;IAC3C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,gCAAgC;IAChC,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;IACtB,uEAAuE;IACvE,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACxC,wBAAwB;IACxB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,cAAc;IACd,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;IAC1B,iCAAiC;IACjC,YAAY,EAAE,iBAAiB;IAC/B,gBAAgB;IAChB,SAAS,EAAE,SAAS,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAGH,yBAAyB;AACzB,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,gBAAgB;IAChB,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC;CACjC,CAAC,CAAC;AAGH,wBAAwB;AACxB,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,KAAK,EAAE,eAAe;CACvB,CAAC,CAAC;AAGH,iEAAiE;AACjE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,iCAAiC;IACjC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,CAAC,CAAC;IACjF,OAAO,EAAE,OAAO;IAChB,gCAAgC;IAChC,QAAQ,EAAE,eAAe,CAAC,QAAQ,EAAE;IACpC,EAAE,EAAE,SAAS;CACd,CAAC,CAAC"}

package/dist/schemas/document.d.ts

@@ -0,0 +1,351 @@
+import { z } from "zod";
+/**
+ * 文档交换协议（design 平面③ / D20）。
+ *
+ * 场景：agent 需要/被要求发送本地文档时，在输出里 emit 一个**指令**（skill 教的格式，
+ * 见 DocumentDirective），phonon 解析后**负责读取本地文件**，打包成附件/其他形式发到服务端。
+ * 也就是说：agent 只说「路径」，读盘 + 传输由 phonon 这一层兜。
+ *
+ * 两个层次要分清：
+ *   - DocumentDirective ：agent ↔ phonon 的指令（含本地 path，skill 教）
+ *   - document.send     ：phonon ↔ server 的线协议（含真实内容/附件）
+ */
+/** 文档用途/形式。 */
+export declare const DocumentKind: z.ZodEnum<["attachment", "document", "image", "file"]>;
+export type DocumentKind = z.infer<typeof DocumentKind>;
+/** 内容承载方式：小文件内联，大文件用 ref 走分块传输（具体待定）。 */
+export declare const DocumentContent: z.ZodUnion<[z.ZodObject<{
+    encoding: z.ZodLiteral<"base64">;
+    data: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    encoding: "base64";
+    data: string;
+}, {
+    encoding: "base64";
+    data: string;
+}>, z.ZodObject<{
+    encoding: z.ZodLiteral<"utf8">;
+    data: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    encoding: "utf8";
+    data: string;
+}, {
+    encoding: "utf8";
+    data: string;
+}>, z.ZodObject<{
+    ref: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    ref: string;
+}, {
+    ref: string;
+}>]>;
+export type DocumentContent = z.infer<typeof DocumentContent>;
+/**
+ * agent 在输出里 emit 的指令格式（skill 教）——只含本地路径与元信息，
+ * phonon 据此读本地文件。**不直接进线协议。**
+ *
+ * 安全（D27 policy）：默认 **project-scoped**——路径必须在绑定项目/worktree 目录内，
+ * 越界需 tenant policy 显式 `allowExternalDocuments`；命中 denyPathPatterns 一律拒。
+ */
+export declare const DocumentDirective: z.ZodObject<{
+    /** 文件路径（默认相对于项目/worktree 根；绝对路径需 policy 允许且在范围内）。 */
+    path: z.ZodString;
+    /** 可选：覆盖文件名（默认取 path 的 basename）。 */
+    name: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<["attachment", "document", "image", "file"]>>;
+    caption: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    kind?: "attachment" | "document" | "image" | "file" | undefined;
+    name?: string | undefined;
+    caption?: string | undefined;
+}, {
+    path: string;
+    kind?: "attachment" | "document" | "image" | "file" | undefined;
+    name?: string | undefined;
+    caption?: string | undefined;
+}>;
+export type DocumentDirective = z.infer<typeof DocumentDirective>;
+/** 单个文档的线上描述（phonon 读完本地文件后封装）。 */
+export declare const DocumentDescriptor: z.ZodObject<{
+    name: z.ZodString;
+    /** 相对项目根的路径（审计/去重用；不暴露设备绝对路径）。 */
+    relativePath: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    kind: z.ZodDefault<z.ZodEnum<["attachment", "document", "image", "file"]>>;
+    caption: z.ZodOptional<z.ZodString>;
+    sizeBytes: z.ZodOptional<z.ZodNumber>;
+    /** 内容 sha256（完整性校验 / 去重）。 */
+    sha256: z.ZodOptional<z.ZodString>;
+    content: z.ZodUnion<[z.ZodObject<{
+        encoding: z.ZodLiteral<"base64">;
+        data: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        encoding: "base64";
+        data: string;
+    }, {
+        encoding: "base64";
+        data: string;
+    }>, z.ZodObject<{
+        encoding: z.ZodLiteral<"utf8">;
+        data: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        encoding: "utf8";
+        data: string;
+    }, {
+        encoding: "utf8";
+        data: string;
+    }>, z.ZodObject<{
+        ref: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        ref: string;
+    }, {
+        ref: string;
+    }>]>;
+}, "strip", z.ZodTypeAny, {
+    kind: "attachment" | "document" | "image" | "file";
+    content: {
+        encoding: "base64";
+        data: string;
+    } | {
+        encoding: "utf8";
+        data: string;
+    } | {
+        ref: string;
+    };
+    name: string;
+    caption?: string | undefined;
+    relativePath?: string | undefined;
+    mimeType?: string | undefined;
+    sizeBytes?: number | undefined;
+    sha256?: string | undefined;
+}, {
+    content: {
+        encoding: "base64";
+        data: string;
+    } | {
+        encoding: "utf8";
+        data: string;
+    } | {
+        ref: string;
+    };
+    name: string;
+    kind?: "attachment" | "document" | "image" | "file" | undefined;
+    caption?: string | undefined;
+    relativePath?: string | undefined;
+    mimeType?: string | undefined;
+    sizeBytes?: number | undefined;
+    sha256?: string | undefined;
+}>;
+export type DocumentDescriptor = z.infer<typeof DocumentDescriptor>;
+export declare const DocumentSendParams: z.ZodObject<{
+    /** 关联会话（通常有；纯设备级发送可省）。 */
+    sessionId: z.ZodOptional<z.ZodBranded<z.ZodString, "SessionId">>;
+    /** 关联轮次（若在某轮对话内触发）。 */
+    turnId: z.ZodOptional<z.ZodString>;
+    documents: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        /** 相对项目根的路径（审计/去重用；不暴露设备绝对路径）。 */
+        relativePath: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        kind: z.ZodDefault<z.ZodEnum<["attachment", "document", "image", "file"]>>;
+        caption: z.ZodOptional<z.ZodString>;
+        sizeBytes: z.ZodOptional<z.ZodNumber>;
+        /** 内容 sha256（完整性校验 / 去重）。 */
+        sha256: z.ZodOptional<z.ZodString>;
+        content: z.ZodUnion<[z.ZodObject<{
+            encoding: z.ZodLiteral<"base64">;
+            data: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            encoding: "base64";
+            data: string;
+        }, {
+            encoding: "base64";
+            data: string;
+        }>, z.ZodObject<{
+            encoding: z.ZodLiteral<"utf8">;
+            data: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            encoding: "utf8";
+            data: string;
+        }, {
+            encoding: "utf8";
+            data: string;
+        }>, z.ZodObject<{
+            ref: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            ref: string;
+        }, {
+            ref: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "attachment" | "document" | "image" | "file";
+        content: {
+            encoding: "base64";
+            data: string;
+        } | {
+            encoding: "utf8";
+            data: string;
+        } | {
+            ref: string;
+        };
+        name: string;
+        caption?: string | undefined;
+        relativePath?: string | undefined;
+        mimeType?: string | undefined;
+        sizeBytes?: number | undefined;
+        sha256?: string | undefined;
+    }, {
+        content: {
+            encoding: "base64";
+            data: string;
+        } | {
+            encoding: "utf8";
+            data: string;
+        } | {
+            ref: string;
+        };
+        name: string;
+        kind?: "attachment" | "document" | "image" | "file" | undefined;
+        caption?: string | undefined;
+        relativePath?: string | undefined;
+        mimeType?: string | undefined;
+        sizeBytes?: number | undefined;
+        sha256?: string | undefined;
+    }>, "many">;
+    at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    at: string;
+    documents: {
+        kind: "attachment" | "document" | "image" | "file";
+        content: {
+            encoding: "base64";
+            data: string;
+        } | {
+            encoding: "utf8";
+            data: string;
+        } | {
+            ref: string;
+        };
+        name: string;
+        caption?: string | undefined;
+        relativePath?: string | undefined;
+        mimeType?: string | undefined;
+        sizeBytes?: number | undefined;
+        sha256?: string | undefined;
+    }[];
+    sessionId?: (string & z.BRAND<"SessionId">) | undefined;
+    turnId?: string | undefined;
+}, {
+    at: string;
+    documents: {
+        content: {
+            encoding: "base64";
+            data: string;
+        } | {
+            encoding: "utf8";
+            data: string;
+        } | {
+            ref: string;
+        };
+        name: string;
+        kind?: "attachment" | "document" | "image" | "file" | undefined;
+        caption?: string | undefined;
+        relativePath?: string | undefined;
+        mimeType?: string | undefined;
+        sizeBytes?: number | undefined;
+        sha256?: string | undefined;
+    }[];
+    sessionId?: string | undefined;
+    turnId?: string | undefined;
+}>;
+export type DocumentSendParams = z.infer<typeof DocumentSendParams>;
+export declare const DocumentSendResult: z.ZodObject<{
+    delivered: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        ok: z.ZodBoolean;
+        /** 服务端落地引用（如云文档 token / 附件 id）。 */
+        serverRef: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        ok: boolean;
+        error?: string | undefined;
+        serverRef?: string | undefined;
+    }, {
+        name: string;
+        ok: boolean;
+        error?: string | undefined;
+        serverRef?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    delivered: {
+        name: string;
+        ok: boolean;
+        error?: string | undefined;
+        serverRef?: string | undefined;
+    }[];
+}, {
+    delivered: {
+        name: string;
+        ok: boolean;
+        error?: string | undefined;
+        serverRef?: string | undefined;
+    }[];
+}>;
+export type DocumentSendResult = z.infer<typeof DocumentSendResult>;
+export declare const DocumentPrepareUploadParams: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodBranded<z.ZodString, "SessionId">>;
+    turnId: z.ZodOptional<z.ZodString>;
+    filename: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    mimeType: z.ZodOptional<z.ZodString>;
+    sha256: z.ZodOptional<z.ZodString>;
+    kind: z.ZodDefault<z.ZodEnum<["attachment", "document", "image", "file"]>>;
+    at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    at: string;
+    kind: "attachment" | "document" | "image" | "file";
+    sizeBytes: number;
+    filename: string;
+    sessionId?: (string & z.BRAND<"SessionId">) | undefined;
+    turnId?: string | undefined;
+    mimeType?: string | undefined;
+    sha256?: string | undefined;
+}, {
+    at: string;
+    sizeBytes: number;
+    filename: string;
+    sessionId?: string | undefined;
+    kind?: "attachment" | "document" | "image" | "file" | undefined;
+    turnId?: string | undefined;
+    mimeType?: string | undefined;
+    sha256?: string | undefined;
+}>;
+export type DocumentPrepareUploadParams = z.infer<typeof DocumentPrepareUploadParams>;
+export declare const DocumentPrepareUploadResult: z.ZodObject<{
+    /** 上传句柄，上传成功后回填到 DocumentContent.ref。 */
+    uploadRef: z.ZodString;
+    /** server 给的 HTTP 上传地址（预签名 URL 等）。 */
+    uploadUrl: z.ZodString;
+    /** HTTP 方法（默认 PUT）。 */
+    method: z.ZodDefault<z.ZodEnum<["PUT", "POST"]>>;
+    /** 需携带的额外请求头。 */
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** 上传地址过期时间。 */
+    expiresAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    uploadRef: string;
+    uploadUrl: string;
+    method: "PUT" | "POST";
+    headers?: Record<string, string> | undefined;
+    expiresAt?: string | undefined;
+}, {
+    uploadRef: string;
+    uploadUrl: string;
+    method?: "PUT" | "POST" | undefined;
+    headers?: Record<string, string> | undefined;
+    expiresAt?: string | undefined;
+}>;
+export type DocumentPrepareUploadResult = z.infer<typeof DocumentPrepareUploadResult>;
+//# sourceMappingURL=document.d.ts.map

package/dist/schemas/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/schemas/document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;GAUG;AAEH,eAAe;AACf,eAAO,MAAM,YAAY,wDAKvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,yCAAyC;AACzC,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;IAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;IAC5B,qDAAqD;;IAErD,qCAAqC;;;;;;;;;;;;;;EAIrC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,mCAAmC;AACnC,eAAO,MAAM,kBAAkB;;IAE7B,kCAAkC;;;;;;IAMlC,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAGpE,eAAO,MAAM,kBAAkB;IAC7B,0BAA0B;;IAE1B,uBAAuB;;;;QAhBvB,kCAAkC;;;;;;QAMlC,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAc7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,eAAO,MAAM,kBAAkB;;;;QAKzB,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKvC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAUpE,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;EAStC,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEtF,eAAO,MAAM,2BAA2B;IACtC,yCAAyC;;IAEzC,sCAAsC;;IAEtC,uBAAuB;;IAEvB,iBAAiB;;IAEjB,gBAAgB;;;;;;;;;;;;;;EAEhB,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}

package/dist/schemas/document.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { SessionId, Timestamp } from "./common.js";
+/**
+ * 文档交换协议（design 平面③ / D20）。
+ *
+ * 场景：agent 需要/被要求发送本地文档时，在输出里 emit 一个**指令**（skill 教的格式，
+ * 见 DocumentDirective），phonon 解析后**负责读取本地文件**，打包成附件/其他形式发到服务端。
+ * 也就是说：agent 只说「路径」，读盘 + 传输由 phonon 这一层兜。
+ *
+ * 两个层次要分清：
+ *   - DocumentDirective ：agent ↔ phonon 的指令（含本地 path，skill 教）
+ *   - document.send     ：phonon ↔ server 的线协议（含真实内容/附件）
+ */
+/** 文档用途/形式。 */
+export const DocumentKind = z.enum([
+    "attachment", // 通用附件
+    "document", // 富文本文档（如 .md → 服务端可转云文档）
+    "image", // 图片
+    "file", // 其他普通文件
+]);
+/** 内容承载方式：小文件内联，大文件用 ref 走分块传输（具体待定）。 */
+export const DocumentContent = z.union([
+    z.object({ encoding: z.literal("base64"), data: z.string() }),
+    z.object({ encoding: z.literal("utf8"), data: z.string() }),
+    z.object({ ref: z.string() }), // 分块传输句柄（大文件，开放问题）
+]);
+/**
+ * agent 在输出里 emit 的指令格式（skill 教）——只含本地路径与元信息，
+ * phonon 据此读本地文件。**不直接进线协议。**
+ *
+ * 安全（D27 policy）：默认 **project-scoped**——路径必须在绑定项目/worktree 目录内，
+ * 越界需 tenant policy 显式 `allowExternalDocuments`；命中 denyPathPatterns 一律拒。
+ */
+export const DocumentDirective = z.object({
+    /** 文件路径（默认相对于项目/worktree 根；绝对路径需 policy 允许且在范围内）。 */
+    path: z.string().min(1),
+    /** 可选：覆盖文件名（默认取 path 的 basename）。 */
+    name: z.string().optional(),
+    kind: DocumentKind.optional(),
+    caption: z.string().optional(),
+});
+/** 单个文档的线上描述（phonon 读完本地文件后封装）。 */
+export const DocumentDescriptor = z.object({
+    name: z.string().min(1),
+    /** 相对项目根的路径（审计/去重用；不暴露设备绝对路径）。 */
+    relativePath: z.string().optional(),
+    mimeType: z.string().optional(),
+    kind: DocumentKind.default("file"),
+    caption: z.string().optional(),
+    sizeBytes: z.number().int().nonnegative().optional(),
+    /** 内容 sha256（完整性校验 / 去重）。 */
+    sha256: z.string().optional(),
+    content: DocumentContent,
+});
+// --- document.send（phonon → server）---
+export const DocumentSendParams = z.object({
+    /** 关联会话（通常有；纯设备级发送可省）。 */
+    sessionId: SessionId.optional(),
+    /** 关联轮次（若在某轮对话内触发）。 */
+    turnId: z.string().optional(),
+    documents: z.array(DocumentDescriptor).min(1),
+    at: Timestamp,
+});
+export const DocumentSendResult = z.object({
+    delivered: z.array(z.object({
+        name: z.string(),
+        ok: z.boolean(),
+        /** 服务端落地引用（如云文档 token / 附件 id）。 */
+        serverRef: z.string().optional(),
+        error: z.string().optional(),
+    })),
+});
+// ===========================================================================
+// 大文件：凭证上传（P1-6 / Gemini#2）
+// 不走 WS 发文件主体（避免内存暴涨/断线重传痛），而是：
+//   phonon → document.prepare_upload {filename,size,mime,sha256}
+//   server → 返回一个 HTTP 上传地址（预签名 URL / 一次性 token）
+//   phonon 本地跑标准 HTTP POST（multipart/流式/断点续传）
+//   上传成功后用 document.send 用 ref 关联回 session
+// ===========================================================================
+export const DocumentPrepareUploadParams = z.object({
+    sessionId: SessionId.optional(),
+    turnId: z.string().optional(),
+    filename: z.string().min(1),
+    sizeBytes: z.number().int().nonnegative(),
+    mimeType: z.string().optional(),
+    sha256: z.string().optional(),
+    kind: DocumentKind.default("file"),
+    at: Timestamp,
+});
+export const DocumentPrepareUploadResult = z.object({
+    /** 上传句柄，上传成功后回填到 DocumentContent.ref。 */
+    uploadRef: z.string(),
+    /** server 给的 HTTP 上传地址（预签名 URL 等）。 */
+    uploadUrl: z.string(),
+    /** HTTP 方法（默认 PUT）。 */
+    method: z.enum(["PUT", "POST"]).default("PUT"),
+    /** 需携带的额外请求头。 */
+    headers: z.record(z.string()).optional(),
+    /** 上传地址过期时间。 */
+    expiresAt: Timestamp.optional(),
+});
+//# sourceMappingURL=document.js.map

package/dist/schemas/document.js.map

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