@agent-phonon/protocol 0.2.0

package/dist/schemas/env.d.ts

@@ -0,0 +1,265 @@
+import { z } from "zod";
+/** Skill / agent 执行环境变量配置。明文存储在设备本地，list 默认脱敏。 */
+export declare const EnvScope: z.ZodEnum<["global", "project", "skill"]>;
+export type EnvScope = z.infer<typeof EnvScope>;
+declare const EnvTargetBase: z.ZodObject<{
+    scope: z.ZodEnum<["global", "project", "skill"]>;
+    projectId: z.ZodOptional<z.ZodBranded<z.ZodString, "ProjectId">>;
+    agent: z.ZodOptional<z.ZodBranded<z.ZodString, "AgentId">>;
+    skillName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    scope: "project" | "global" | "skill";
+    agent?: (string & z.BRAND<"AgentId">) | undefined;
+    projectId?: (string & z.BRAND<"ProjectId">) | undefined;
+    skillName?: string | undefined;
+}, {
+    scope: "project" | "global" | "skill";
+    agent?: string | undefined;
+    projectId?: string | undefined;
+    skillName?: string | undefined;
+}>;
+export declare const EnvTarget: z.ZodObject<{
+    scope: z.ZodEnum<["global", "project", "skill"]>;
+    projectId: z.ZodOptional<z.ZodBranded<z.ZodString, "ProjectId">>;
+    agent: z.ZodOptional<z.ZodBranded<z.ZodString, "AgentId">>;
+    skillName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    scope: "project" | "global" | "skill";
+    agent?: (string & z.BRAND<"AgentId">) | undefined;
+    projectId?: (string & z.BRAND<"ProjectId">) | undefined;
+    skillName?: string | undefined;
+}, {
+    scope: "project" | "global" | "skill";
+    agent?: string | undefined;
+    projectId?: string | undefined;
+    skillName?: string | undefined;
+}>;
+export type EnvTarget = z.infer<typeof EnvTargetBase>;
+export declare const EnvVarDescriptor: z.ZodObject<{
+    scope: z.ZodEnum<["global", "project", "skill"]>;
+    projectId: z.ZodOptional<z.ZodBranded<z.ZodString, "ProjectId">>;
+    agent: z.ZodOptional<z.ZodBranded<z.ZodString, "AgentId">>;
+    skillName: z.ZodOptional<z.ZodString>;
+} & {
+    name: z.ZodString;
+    value: z.ZodOptional<z.ZodString>;
+    redacted: z.ZodDefault<z.ZodBoolean>;
+    updatedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    scope: "project" | "global" | "skill";
+    redacted: boolean;
+    value?: string | undefined;
+    agent?: (string & z.BRAND<"AgentId">) | undefined;
+    projectId?: (string & z.BRAND<"ProjectId">) | undefined;
+    skillName?: string | undefined;
+    updatedAt?: string | undefined;
+}, {
+    name: string;
+    scope: "project" | "global" | "skill";
+    value?: string | undefined;
+    agent?: string | undefined;
+    projectId?: string | undefined;
+    skillName?: string | undefined;
+    redacted?: boolean | undefined;
+    updatedAt?: string | undefined;
+}>;
+export type EnvVarDescriptor = z.infer<typeof EnvVarDescriptor>;
+export declare const EnvSetParams: z.ZodObject<{
+    scope: z.ZodEnum<["global", "project", "skill"]>;
+    projectId: z.ZodOptional<z.ZodBranded<z.ZodString, "ProjectId">>;
+    agent: z.ZodOptional<z.ZodBranded<z.ZodString, "AgentId">>;
+    skillName: z.ZodOptional<z.ZodString>;
+} & {
+    clientRequestId: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    value: z.ZodString;
+    /** 可选：如果是 secret，list 默认永远脱敏。默认 true。 */
+    secret: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    name: string;
+    scope: "project" | "global" | "skill";
+    secret: boolean;
+    agent?: (string & z.BRAND<"AgentId">) | undefined;
+    clientRequestId?: string | undefined;
+    projectId?: (string & z.BRAND<"ProjectId">) | undefined;
+    skillName?: string | undefined;
+}, {
+    value: string;
+    name: string;
+    scope: "project" | "global" | "skill";
+    agent?: string | undefined;
+    clientRequestId?: string | undefined;
+    projectId?: string | undefined;
+    skillName?: string | undefined;
+    secret?: boolean | undefined;
+}>;
+export type EnvSetParams = z.infer<typeof EnvSetParams>;
+export declare const EnvSetResult: z.ZodObject<{
+    variable: z.ZodObject<{
+        scope: z.ZodEnum<["global", "project", "skill"]>;
+        projectId: z.ZodOptional<z.ZodBranded<z.ZodString, "ProjectId">>;
+        agent: z.ZodOptional<z.ZodBranded<z.ZodString, "AgentId">>;
+        skillName: z.ZodOptional<z.ZodString>;
+    } & {
+        name: z.ZodString;
+        value: z.ZodOptional<z.ZodString>;
+        redacted: z.ZodDefault<z.ZodBoolean>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        scope: "project" | "global" | "skill";
+        redacted: boolean;
+        value?: string | undefined;
+        agent?: (string & z.BRAND<"AgentId">) | undefined;
+        projectId?: (string & z.BRAND<"ProjectId">) | undefined;
+        skillName?: string | undefined;
+        updatedAt?: string | undefined;
+    }, {
+        name: string;
+        scope: "project" | "global" | "skill";
+        value?: string | undefined;
+        agent?: string | undefined;
+        projectId?: string | undefined;
+        skillName?: string | undefined;
+        redacted?: boolean | undefined;
+        updatedAt?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    variable: {
+        name: string;
+        scope: "project" | "global" | "skill";
+        redacted: boolean;
+        value?: string | undefined;
+        agent?: (string & z.BRAND<"AgentId">) | undefined;
+        projectId?: (string & z.BRAND<"ProjectId">) | undefined;
+        skillName?: string | undefined;
+        updatedAt?: string | undefined;
+    };
+}, {
+    variable: {
+        name: string;
+        scope: "project" | "global" | "skill";
+        value?: string | undefined;
+        agent?: string | undefined;
+        projectId?: string | undefined;
+        skillName?: string | undefined;
+        redacted?: boolean | undefined;
+        updatedAt?: string | undefined;
+    };
+}>;
+export type EnvSetResult = z.infer<typeof EnvSetResult>;
+export declare const EnvListParams: z.ZodObject<{
+    scope: z.ZodOptional<z.ZodEnum<["global", "project", "skill"]>>;
+    projectId: z.ZodOptional<z.ZodOptional<z.ZodBranded<z.ZodString, "ProjectId">>>;
+    agent: z.ZodOptional<z.ZodOptional<z.ZodBranded<z.ZodString, "AgentId">>>;
+    skillName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+} & {
+    /** 默认 false；true 需要本地 policy allowEnvReveal。 */
+    reveal: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    reveal: boolean;
+    agent?: (string & z.BRAND<"AgentId">) | undefined;
+    scope?: "project" | "global" | "skill" | undefined;
+    projectId?: (string & z.BRAND<"ProjectId">) | undefined;
+    skillName?: string | undefined;
+}, {
+    agent?: string | undefined;
+    scope?: "project" | "global" | "skill" | undefined;
+    projectId?: string | undefined;
+    skillName?: string | undefined;
+    reveal?: boolean | undefined;
+}>;
+export type EnvListParams = z.infer<typeof EnvListParams>;
+export declare const EnvListResult: z.ZodObject<{
+    variables: z.ZodArray<z.ZodObject<{
+        scope: z.ZodEnum<["global", "project", "skill"]>;
+        projectId: z.ZodOptional<z.ZodBranded<z.ZodString, "ProjectId">>;
+        agent: z.ZodOptional<z.ZodBranded<z.ZodString, "AgentId">>;
+        skillName: z.ZodOptional<z.ZodString>;
+    } & {
+        name: z.ZodString;
+        value: z.ZodOptional<z.ZodString>;
+        redacted: z.ZodDefault<z.ZodBoolean>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        scope: "project" | "global" | "skill";
+        redacted: boolean;
+        value?: string | undefined;
+        agent?: (string & z.BRAND<"AgentId">) | undefined;
+        projectId?: (string & z.BRAND<"ProjectId">) | undefined;
+        skillName?: string | undefined;
+        updatedAt?: string | undefined;
+    }, {
+        name: string;
+        scope: "project" | "global" | "skill";
+        value?: string | undefined;
+        agent?: string | undefined;
+        projectId?: string | undefined;
+        skillName?: string | undefined;
+        redacted?: boolean | undefined;
+        updatedAt?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    variables: {
+        name: string;
+        scope: "project" | "global" | "skill";
+        redacted: boolean;
+        value?: string | undefined;
+        agent?: (string & z.BRAND<"AgentId">) | undefined;
+        projectId?: (string & z.BRAND<"ProjectId">) | undefined;
+        skillName?: string | undefined;
+        updatedAt?: string | undefined;
+    }[];
+}, {
+    variables: {
+        name: string;
+        scope: "project" | "global" | "skill";
+        value?: string | undefined;
+        agent?: string | undefined;
+        projectId?: string | undefined;
+        skillName?: string | undefined;
+        redacted?: boolean | undefined;
+        updatedAt?: string | undefined;
+    }[];
+}>;
+export type EnvListResult = z.infer<typeof EnvListResult>;
+export declare const EnvDeleteParams: z.ZodObject<{
+    scope: z.ZodEnum<["global", "project", "skill"]>;
+    projectId: z.ZodOptional<z.ZodBranded<z.ZodString, "ProjectId">>;
+    agent: z.ZodOptional<z.ZodBranded<z.ZodString, "AgentId">>;
+    skillName: z.ZodOptional<z.ZodString>;
+} & {
+    clientRequestId: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    scope: "project" | "global" | "skill";
+    agent?: (string & z.BRAND<"AgentId">) | undefined;
+    clientRequestId?: string | undefined;
+    projectId?: (string & z.BRAND<"ProjectId">) | undefined;
+    skillName?: string | undefined;
+}, {
+    name: string;
+    scope: "project" | "global" | "skill";
+    agent?: string | undefined;
+    clientRequestId?: string | undefined;
+    projectId?: string | undefined;
+    skillName?: string | undefined;
+}>;
+export type EnvDeleteParams = z.infer<typeof EnvDeleteParams>;
+export declare const EnvDeleteResult: z.ZodObject<{
+    deleted: z.ZodLiteral<true>;
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    deleted: true;
+}, {
+    name: string;
+    deleted: true;
+}>;
+export type EnvDeleteResult = z.infer<typeof EnvDeleteResult>;
+export {};
+//# sourceMappingURL=env.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/schemas/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,kDAAkD;AAClD,eAAO,MAAM,QAAQ,2CAAyC,CAAC;AAC/D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;EAKjB,CAAC;AAWH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;EAAqC,CAAC;AAC5D,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEtD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAK1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,eAAO,MAAM,YAAY;;;;;;;;;IAIvB,yCAAyC;;;;;;;;;;;;;;;;;;;;EAExC,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACxD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA2C,CAAC;AACrE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,eAAO,MAAM,aAAa;;;;;;IACxB,gDAAgD;;;;;;;;;;;;;;EAEhD,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAC1D,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAqD,CAAC;AAChF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;EAGzB,CAAC;AACJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAC9D,eAAO,MAAM,eAAe;;;;;;;;;EAA2D,CAAC;AACxF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/schemas/env.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { ProjectId, AgentId } from "./common.js";
+/** Skill / agent 执行环境变量配置。明文存储在设备本地，list 默认脱敏。 */
+export const EnvScope = z.enum(["global", "project", "skill"]);
+const EnvTargetBase = z.object({
+    scope: EnvScope,
+    projectId: ProjectId.optional(),
+    agent: AgentId.optional(),
+    skillName: z.string().min(1).optional(),
+});
+function withEnvTargetRefine(schema) {
+    return schema
+        .refine((v) => v.scope !== "project" || !!v.projectId, { message: "project scope requires projectId", path: ["projectId"] })
+        .refine((v) => {
+        const x = v;
+        return x.scope !== "skill" || (!!x.projectId && !!x.agent && !!x.skillName);
+    }, { message: "skill scope requires projectId+agent+skillName", path: ["skillName"] });
+}
+export const EnvTarget = withEnvTargetRefine(EnvTargetBase);
+export const EnvVarDescriptor = withEnvTargetRefine(EnvTargetBase.extend({
+    name: z.string().min(1),
+    value: z.string().optional(),
+    redacted: z.boolean().default(true),
+    updatedAt: z.string().datetime({ offset: true }).optional(),
+}));
+export const EnvSetParams = withEnvTargetRefine(EnvTargetBase.extend({
+    clientRequestId: z.string().optional(),
+    name: z.string().min(1),
+    value: z.string(),
+    /** 可选：如果是 secret，list 默认永远脱敏。默认 true。 */
+    secret: z.boolean().default(true),
+}));
+export const EnvSetResult = z.object({ variable: EnvVarDescriptor });
+export const EnvListParams = EnvTargetBase.partial().extend({
+    /** 默认 false；true 需要本地 policy allowEnvReveal。 */
+    reveal: z.boolean().default(false),
+});
+export const EnvListResult = z.object({ variables: z.array(EnvVarDescriptor) });
+export const EnvDeleteParams = withEnvTargetRefine(EnvTargetBase.extend({
+    clientRequestId: z.string().optional(),
+    name: z.string().min(1),
+}));
+export const EnvDeleteResult = z.object({ deleted: z.literal(true), name: z.string() });
+//# sourceMappingURL=env.js.map

package/dist/schemas/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/schemas/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEjD,kDAAkD;AAClD,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;AAG/D,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,KAAK,EAAE,QAAQ;IACf,SAAS,EAAE,SAAS,CAAC,QAAQ,EAAE;IAC/B,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE;IACzB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEH,SAAS,mBAAmB,CAAyB,MAAS;IAC5D,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,CAAU,EAAE,EAAE,CAAE,CAA4C,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,CAAE,CAA4B,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,kCAAkC,EAAE,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC;SAC5M,MAAM,CAAC,CAAC,CAAU,EAAE,EAAE;QACrB,MAAM,CAAC,GAAG,CAA+E,CAAC;QAC1F,OAAO,CAAC,CAAC,KAAK,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC9E,CAAC,EAAE,EAAE,OAAO,EAAE,gDAAgD,EAAE,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE,CAAiB,CAAC;AAC3G,CAAC;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,mBAAmB,CAAC,aAAa,CAAC,CAAC;AAG5D,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,aAAa,CAAC,MAAM,CAAC;IACvE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC5D,CAAC,CAAC,CAAC;AAGJ,MAAM,CAAC,MAAM,YAAY,GAAG,mBAAmB,CAAC,aAAa,CAAC,MAAM,CAAC;IACnE,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACtC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,yCAAyC;IACzC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CAClC,CAAC,CAAC,CAAC;AAEJ,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAGrE,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC;IAC1D,gDAAgD;IAChD,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;CACnC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;AAGhF,MAAM,CAAC,MAAM,eAAe,GAAG,mBAAmB,CAAC,aAAa,CAAC,MAAM,CAAC;IACtE,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACtC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACxB,CAAC,CAAC,CAAC;AAEJ,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC"}

package/dist/schemas/file.d.ts

@@ -0,0 +1,274 @@
+import { z } from "zod";
+/**
+ * 受控工作区文件读写协议。
+ *
+ * 与 document.send 不同：document.send 是 agent 主动把产物发给 server；
+ * file.* 是 server 主动读写本地 project/worktree 内文件。
+ */
+export declare const FileEncoding: z.ZodEnum<["utf8", "base64"]>;
+export type FileEncoding = z.infer<typeof FileEncoding>;
+export declare const FileScope: z.ZodObject<{
+    projectId: z.ZodBranded<z.ZodString, "ProjectId">;
+    /** 可选：指定 worktree；缺省为项目主目录。 */
+    worktreeId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    projectId: string & z.BRAND<"ProjectId">;
+    worktreeId?: string | undefined;
+}, {
+    projectId: string;
+    worktreeId?: string | undefined;
+}>;
+export type FileScope = z.infer<typeof FileScope>;
+export declare const FileStat: z.ZodObject<{
+    path: z.ZodString;
+    type: z.ZodEnum<["file", "directory", "symlink", "other"]>;
+    sizeBytes: z.ZodNumber;
+    modifiedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    type: "file" | "directory" | "symlink" | "other";
+    sizeBytes: number;
+    modifiedAt?: string | undefined;
+}, {
+    path: string;
+    type: "file" | "directory" | "symlink" | "other";
+    sizeBytes: number;
+    modifiedAt?: string | undefined;
+}>;
+export type FileStat = z.infer<typeof FileStat>;
+export declare const FileReadParams: z.ZodObject<{
+    projectId: z.ZodBranded<z.ZodString, "ProjectId">;
+    /** 可选：指定 worktree；缺省为项目主目录。 */
+    worktreeId: z.ZodOptional<z.ZodString>;
+} & {
+    path: z.ZodEffects<z.ZodString, string, string>;
+    encoding: z.ZodDefault<z.ZodEnum<["utf8", "base64"]>>;
+    /** 可选：最大读取字节数，避免误读超大文件。 */
+    maxBytes: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    encoding: "base64" | "utf8";
+    projectId: string & z.BRAND<"ProjectId">;
+    worktreeId?: string | undefined;
+    maxBytes?: number | undefined;
+}, {
+    path: string;
+    projectId: string;
+    worktreeId?: string | undefined;
+    encoding?: "base64" | "utf8" | undefined;
+    maxBytes?: number | undefined;
+}>;
+export type FileReadParams = z.infer<typeof FileReadParams>;
+export declare const FileReadResult: z.ZodObject<{
+    path: z.ZodString;
+    encoding: z.ZodEnum<["utf8", "base64"]>;
+    data: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    truncated: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    encoding: "base64" | "utf8";
+    data: string;
+    sizeBytes: number;
+    truncated: boolean;
+}, {
+    path: string;
+    encoding: "base64" | "utf8";
+    data: string;
+    sizeBytes: number;
+    truncated?: boolean | undefined;
+}>;
+export type FileReadResult = z.infer<typeof FileReadResult>;
+export declare const FileWriteParams: z.ZodObject<{
+    projectId: z.ZodBranded<z.ZodString, "ProjectId">;
+    /** 可选：指定 worktree；缺省为项目主目录。 */
+    worktreeId: z.ZodOptional<z.ZodString>;
+} & {
+    /** 可选：幂等键。 */
+    clientRequestId: z.ZodOptional<z.ZodString>;
+    path: z.ZodEffects<z.ZodString, string, string>;
+    encoding: z.ZodDefault<z.ZodEnum<["utf8", "base64"]>>;
+    data: z.ZodString;
+    /** 缺省 true；false 时若文件已存在则报错。 */
+    overwrite: z.ZodDefault<z.ZodBoolean>;
+    /** 是否自动创建父目录。 */
+    createDirs: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    encoding: "base64" | "utf8";
+    data: string;
+    projectId: string & z.BRAND<"ProjectId">;
+    overwrite: boolean;
+    createDirs: boolean;
+    clientRequestId?: string | undefined;
+    worktreeId?: string | undefined;
+}, {
+    path: string;
+    data: string;
+    projectId: string;
+    clientRequestId?: string | undefined;
+    worktreeId?: string | undefined;
+    encoding?: "base64" | "utf8" | undefined;
+    overwrite?: boolean | undefined;
+    createDirs?: boolean | undefined;
+}>;
+export type FileWriteParams = z.infer<typeof FileWriteParams>;
+export declare const FileWriteResult: z.ZodObject<{
+    path: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    written: z.ZodLiteral<true>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    sizeBytes: number;
+    written: true;
+}, {
+    path: string;
+    sizeBytes: number;
+    written: true;
+}>;
+export type FileWriteResult = z.infer<typeof FileWriteResult>;
+export declare const FileListParams: z.ZodObject<{
+    projectId: z.ZodBranded<z.ZodString, "ProjectId">;
+    /** 可选：指定 worktree；缺省为项目主目录。 */
+    worktreeId: z.ZodOptional<z.ZodString>;
+} & {
+    path: z.ZodDefault<z.ZodEffects<z.ZodString, string, string>>;
+    recursive: z.ZodDefault<z.ZodBoolean>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    limit: number;
+    projectId: string & z.BRAND<"ProjectId">;
+    recursive: boolean;
+    worktreeId?: string | undefined;
+}, {
+    projectId: string;
+    path?: string | undefined;
+    worktreeId?: string | undefined;
+    limit?: number | undefined;
+    recursive?: boolean | undefined;
+}>;
+export type FileListParams = z.infer<typeof FileListParams>;
+export declare const FileListResult: z.ZodObject<{
+    path: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        type: z.ZodEnum<["file", "directory", "symlink", "other"]>;
+        sizeBytes: z.ZodNumber;
+        modifiedAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        type: "file" | "directory" | "symlink" | "other";
+        sizeBytes: number;
+        modifiedAt?: string | undefined;
+    }, {
+        path: string;
+        type: "file" | "directory" | "symlink" | "other";
+        sizeBytes: number;
+        modifiedAt?: string | undefined;
+    }>, "many">;
+    truncated: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    entries: {
+        path: string;
+        type: "file" | "directory" | "symlink" | "other";
+        sizeBytes: number;
+        modifiedAt?: string | undefined;
+    }[];
+    path: string;
+    truncated: boolean;
+}, {
+    entries: {
+        path: string;
+        type: "file" | "directory" | "symlink" | "other";
+        sizeBytes: number;
+        modifiedAt?: string | undefined;
+    }[];
+    path: string;
+    truncated?: boolean | undefined;
+}>;
+export type FileListResult = z.infer<typeof FileListResult>;
+export declare const FileStatParams: z.ZodObject<{
+    projectId: z.ZodBranded<z.ZodString, "ProjectId">;
+    /** 可选：指定 worktree；缺省为项目主目录。 */
+    worktreeId: z.ZodOptional<z.ZodString>;
+} & {
+    path: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    projectId: string & z.BRAND<"ProjectId">;
+    worktreeId?: string | undefined;
+}, {
+    path: string;
+    projectId: string;
+    worktreeId?: string | undefined;
+}>;
+export type FileStatParams = z.infer<typeof FileStatParams>;
+export declare const FileStatResult: z.ZodObject<{
+    stat: z.ZodObject<{
+        path: z.ZodString;
+        type: z.ZodEnum<["file", "directory", "symlink", "other"]>;
+        sizeBytes: z.ZodNumber;
+        modifiedAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        type: "file" | "directory" | "symlink" | "other";
+        sizeBytes: number;
+        modifiedAt?: string | undefined;
+    }, {
+        path: string;
+        type: "file" | "directory" | "symlink" | "other";
+        sizeBytes: number;
+        modifiedAt?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    stat: {
+        path: string;
+        type: "file" | "directory" | "symlink" | "other";
+        sizeBytes: number;
+        modifiedAt?: string | undefined;
+    };
+}, {
+    stat: {
+        path: string;
+        type: "file" | "directory" | "symlink" | "other";
+        sizeBytes: number;
+        modifiedAt?: string | undefined;
+    };
+}>;
+export type FileStatResult = z.infer<typeof FileStatResult>;
+export declare const FileMkdirParams: z.ZodObject<{
+    projectId: z.ZodBranded<z.ZodString, "ProjectId">;
+    /** 可选：指定 worktree；缺省为项目主目录。 */
+    worktreeId: z.ZodOptional<z.ZodString>;
+} & {
+    /** 可选：幂等键。 */
+    clientRequestId: z.ZodOptional<z.ZodString>;
+    path: z.ZodEffects<z.ZodString, string, string>;
+    recursive: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    projectId: string & z.BRAND<"ProjectId">;
+    recursive: boolean;
+    clientRequestId?: string | undefined;
+    worktreeId?: string | undefined;
+}, {
+    path: string;
+    projectId: string;
+    clientRequestId?: string | undefined;
+    worktreeId?: string | undefined;
+    recursive?: boolean | undefined;
+}>;
+export type FileMkdirParams = z.infer<typeof FileMkdirParams>;
+export declare const FileMkdirResult: z.ZodObject<{
+    path: z.ZodString;
+    created: z.ZodLiteral<true>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    created: true;
+}, {
+    path: string;
+    created: true;
+}>;
+export type FileMkdirResult = z.infer<typeof FileMkdirResult>;
+//# sourceMappingURL=file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/schemas/file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,eAAO,MAAM,YAAY,+BAA6B,CAAC;AACvD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,eAAO,MAAM,SAAS;;IAEpB,+BAA+B;;;;;;;;EAE/B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAMlD,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;EAKnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,eAAO,MAAM,cAAc;;IAjBzB,+BAA+B;;;;;IAoB/B,2BAA2B;;;;;;;;;;;;;;EAE3B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;EAMzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,eAAe;;IAlC1B,+BAA+B;;;IAmC/B,cAAc;;;;;IAKd,gCAAgC;;IAEhC,iBAAiB;;;;;;;;;;;;;;;;;;;;EAEjB,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,eAAe;;;;;;;;;;;;EAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,cAAc;;IAtDzB,+BAA+B;;;;;;;;;;;;;;;;;;EA0D/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAIzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,cAAc;;IApEzB,+BAA+B;;;;;;;;;;;;EAoEqC,CAAC;AACvE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC5D,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA+B,CAAC;AAC3D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,eAAe;;IAzE1B,+BAA+B;;;IA0E/B,cAAc;;;;;;;;;;;;;;;;EAId,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAC9D,eAAO,MAAM,eAAe;;;;;;;;;EAA2D,CAAC;AACxF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/schemas/file.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { ProjectId } from "./common.js";
+/**
+ * 受控工作区文件读写协议。
+ *
+ * 与 document.send 不同：document.send 是 agent 主动把产物发给 server；
+ * file.* 是 server 主动读写本地 project/worktree 内文件。
+ */
+export const FileEncoding = z.enum(["utf8", "base64"]);
+export const FileScope = z.object({
+    projectId: ProjectId,
+    /** 可选：指定 worktree；缺省为项目主目录。 */
+    worktreeId: z.string().min(1).optional(),
+});
+const RelativePath = z.string().min(1).refine((p) => !p.startsWith("/") && !p.includes("\0"), {
+    message: "path must be a relative path",
+});
+export const FileStat = z.object({
+    path: z.string(),
+    type: z.enum(["file", "directory", "symlink", "other"]),
+    sizeBytes: z.number().nonnegative(),
+    modifiedAt: z.string().datetime({ offset: true }).optional(),
+});
+export const FileReadParams = FileScope.extend({
+    path: RelativePath,
+    encoding: FileEncoding.default("utf8"),
+    /** 可选：最大读取字节数，避免误读超大文件。 */
+    maxBytes: z.number().int().positive().optional(),
+});
+export const FileReadResult = z.object({
+    path: z.string(),
+    encoding: FileEncoding,
+    data: z.string(),
+    sizeBytes: z.number().nonnegative(),
+    truncated: z.boolean().default(false),
+});
+export const FileWriteParams = FileScope.extend({
+    /** 可选：幂等键。 */
+    clientRequestId: z.string().optional(),
+    path: RelativePath,
+    encoding: FileEncoding.default("utf8"),
+    data: z.string(),
+    /** 缺省 true；false 时若文件已存在则报错。 */
+    overwrite: z.boolean().default(true),
+    /** 是否自动创建父目录。 */
+    createDirs: z.boolean().default(true),
+});
+export const FileWriteResult = z.object({
+    path: z.string(),
+    sizeBytes: z.number().nonnegative(),
+    written: z.literal(true),
+});
+export const FileListParams = FileScope.extend({
+    path: RelativePath.default("."),
+    recursive: z.boolean().default(false),
+    limit: z.number().int().positive().max(10000).default(500),
+});
+export const FileListResult = z.object({
+    path: z.string(),
+    entries: z.array(FileStat),
+    truncated: z.boolean().default(false),
+});
+export const FileStatParams = FileScope.extend({ path: RelativePath });
+export const FileStatResult = z.object({ stat: FileStat });
+export const FileMkdirParams = FileScope.extend({
+    /** 可选：幂等键。 */
+    clientRequestId: z.string().optional(),
+    path: RelativePath,
+    recursive: z.boolean().default(true),
+});
+export const FileMkdirResult = z.object({ path: z.string(), created: z.literal(true) });
+//# sourceMappingURL=file.js.map

package/dist/schemas/file.js.map

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