@agent-phonon/protocol 0.2.0

package/dist/schemas/hook.d.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+/**
+ * Hook / 人在回路 HITL（design §8）。
+ *
+ * 核心：phonon 自己不实现人在回路，只做事件中转 + 阻塞等裁决。
+ *   phonon → server : hook.fired   （到 hook 点抛事件）
+ *   server → phonon : hook.resolve （裁决；服务端决定是否问真人、怎么问、等多久）
+ */
+/** hook 触发载荷（phonon → server）。 */
+export declare const HookFiredParams: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    /** 本次 hook 的唯一 id，hook.resolve 用它配对。 */
+    hookId: z.ZodString;
+    hookType: z.ZodEnum<["pre_tool", "post_tool", "pre_command", "pre_file_write", "pre_network", "session_start", "session_end", "notification"]>;
+    /** 触发上下文：被拦截的操作详情（命令、工具名、参数、文件路径等）。 */
+    payload: z.ZodDefault<z.ZodObject<{
+        toolName: z.ZodOptional<z.ZodString>;
+        command: z.ZodOptional<z.ZodString>;
+        filePath: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        /** 其余 adapter 特定字段。 */
+        extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        toolName?: string | undefined;
+        command?: string | undefined;
+        filePath?: string | undefined;
+        url?: string | undefined;
+        extra?: Record<string, unknown> | undefined;
+    }, {
+        toolName?: string | undefined;
+        command?: string | undefined;
+        filePath?: string | undefined;
+        url?: string | undefined;
+        extra?: Record<string, unknown> | undefined;
+    }>>;
+    /** 该 turn 的关联 id（若在某轮对话内触发）。 */
+    turnId: z.ZodOptional<z.ZodString>;
+    at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    at: string;
+    sessionId: string & z.BRAND<"SessionId">;
+    hookId: string;
+    hookType: "pre_tool" | "post_tool" | "pre_command" | "pre_file_write" | "pre_network" | "session_start" | "session_end" | "notification";
+    payload: {
+        toolName?: string | undefined;
+        command?: string | undefined;
+        filePath?: string | undefined;
+        url?: string | undefined;
+        extra?: Record<string, unknown> | undefined;
+    };
+    turnId?: string | undefined;
+}, {
+    at: string;
+    sessionId: string;
+    hookId: string;
+    hookType: "pre_tool" | "post_tool" | "pre_command" | "pre_file_write" | "pre_network" | "session_start" | "session_end" | "notification";
+    turnId?: string | undefined;
+    payload?: {
+        toolName?: string | undefined;
+        command?: string | undefined;
+        filePath?: string | undefined;
+        url?: string | undefined;
+        extra?: Record<string, unknown> | undefined;
+    } | undefined;
+}>;
+export type HookFiredParams = z.infer<typeof HookFiredParams>;
+/**
+ * 裁决动作（server → phonon）。
+ * - continue : 放行，照常执行
+ * - inject   : 先注入上下文再继续（用 context 字段）
+ * - modify   : 用修改后的参数继续（用 patch 字段，如改写命令）
+ * - abort    : 中止该操作（可带原因）
+ */
+export declare const HookAction: z.ZodEnum<["continue", "inject", "modify", "abort"]>;
+export type HookAction = z.infer<typeof HookAction>;
+export declare const HookResolveParams: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    /** 必须与对应 hook.fired 的 hookId 一致。 */
+    hookId: z.ZodString;
+    action: z.ZodEnum<["continue", "inject", "modify", "abort"]>;
+    /** action=inject 时：要注入的上下文。 */
+    context: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["system", "user", "assistant"]>;
+        content: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }, {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>, "many">>;
+    /** action=modify 时：对被拦截操作的修改（结构与该 hook 的 payload 对应）。 */
+    patch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** action=abort 时：可选原因，会回传给 agent / 记录。 */
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+    hookId: string;
+    action: "inject" | "continue" | "modify" | "abort";
+    reason?: string | undefined;
+    context?: {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }[] | undefined;
+    patch?: Record<string, unknown> | undefined;
+}, {
+    sessionId: string;
+    hookId: string;
+    action: "inject" | "continue" | "modify" | "abort";
+    reason?: string | undefined;
+    context?: {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }[] | undefined;
+    patch?: Record<string, unknown> | undefined;
+}>;
+export type HookResolveParams = z.infer<typeof HookResolveParams>;
+export declare const HookResolveResult: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    hookId: z.ZodString;
+    applied: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+    hookId: string;
+    applied: boolean;
+}, {
+    sessionId: string;
+    hookId: string;
+    applied: boolean;
+}>;
+export type HookResolveResult = z.infer<typeof HookResolveResult>;
+//# sourceMappingURL=hook.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../src/schemas/hook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;GAMG;AAEH,kCAAkC;AAClC,eAAO,MAAM,eAAe;;IAE1B,wCAAwC;;;IAGxC,uCAAuC;;;;;;QAOnC,uBAAuB;;;;;;;;;;;;;;;IAI3B,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,sDAAoD,CAAC;AAC5E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,iBAAiB;;IAE5B,oCAAoC;;;IAGpC,+BAA+B;;;;;;;;;;;IAE/B,yDAAyD;;IAEzD,2CAA2C;;;;;;;;;;;;;;;;;;;;;;EAE3C,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;EAI5B,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/schemas/hook.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { SessionId, Timestamp } from "./common.js";
+import { HookType } from "./capabilities.js";
+import { ContextItem } from "./session.js";
+/**
+ * Hook / 人在回路 HITL（design §8）。
+ *
+ * 核心：phonon 自己不实现人在回路，只做事件中转 + 阻塞等裁决。
+ *   phonon → server : hook.fired   （到 hook 点抛事件）
+ *   server → phonon : hook.resolve （裁决；服务端决定是否问真人、怎么问、等多久）
+ */
+/** hook 触发载荷（phonon → server）。 */
+export const HookFiredParams = z.object({
+    sessionId: SessionId,
+    /** 本次 hook 的唯一 id，hook.resolve 用它配对。 */
+    hookId: z.string().min(1),
+    hookType: HookType,
+    /** 触发上下文：被拦截的操作详情（命令、工具名、参数、文件路径等）。 */
+    payload: z
+        .object({
+        toolName: z.string().optional(),
+        command: z.string().optional(),
+        filePath: z.string().optional(),
+        url: z.string().optional(),
+        /** 其余 adapter 特定字段。 */
+        extra: z.record(z.unknown()).optional(),
+    })
+        .default({}),
+    /** 该 turn 的关联 id（若在某轮对话内触发）。 */
+    turnId: z.string().optional(),
+    at: Timestamp,
+});
+/**
+ * 裁决动作（server → phonon）。
+ * - continue : 放行，照常执行
+ * - inject   : 先注入上下文再继续（用 context 字段）
+ * - modify   : 用修改后的参数继续（用 patch 字段，如改写命令）
+ * - abort    : 中止该操作（可带原因）
+ */
+export const HookAction = z.enum(["continue", "inject", "modify", "abort"]);
+export const HookResolveParams = z.object({
+    sessionId: SessionId,
+    /** 必须与对应 hook.fired 的 hookId 一致。 */
+    hookId: z.string().min(1),
+    action: HookAction,
+    /** action=inject 时：要注入的上下文。 */
+    context: z.array(ContextItem).optional(),
+    /** action=modify 时：对被拦截操作的修改（结构与该 hook 的 payload 对应）。 */
+    patch: z.record(z.unknown()).optional(),
+    /** action=abort 时：可选原因，会回传给 agent / 记录。 */
+    reason: z.string().optional(),
+});
+export const HookResolveResult = z.object({
+    sessionId: SessionId,
+    hookId: z.string(),
+    applied: z.boolean(),
+});
+//# sourceMappingURL=hook.js.map

package/dist/schemas/hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.js","sourceRoot":"","sources":["../../src/schemas/hook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;GAMG;AAEH,kCAAkC;AAClC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,SAAS,EAAE,SAAS;IACpB,wCAAwC;IACxC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,QAAQ,EAAE,QAAQ;IAClB,uCAAuC;IACvC,OAAO,EAAE,CAAC;SACP,MAAM,CAAC;QACN,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC/B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC9B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC/B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC1B,uBAAuB;QACvB,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;KACxC,CAAC;SACD,OAAO,CAAC,EAAE,CAAC;IACd,gCAAgC;IAChC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,EAAE,EAAE,SAAS;CACd,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAG5E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,SAAS,EAAE,SAAS;IACpB,oCAAoC;IACpC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,MAAM,EAAE,UAAU;IAClB,+BAA+B;IAC/B,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE;IACxC,yDAAyD;IACzD,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IACvC,2CAA2C;IAC3C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,SAAS,EAAE,SAAS;IACpB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;CACrB,CAAC,CAAC"}