@downcity/agent 1.1.438 → 1.1.445

package/src/session/input/SessionHookRunner.ts

@@ -0,0 +1,100 @@
+/**
+ * Session 检查点执行器。
+ *
+ * 扩展能力编译后提供三类普通函数；本模块负责按检查点取出处理器、串行执行，
+ * 并把失败隔离到单个检查点。Agent 内部只有这一个地方调用扩展处理器。
+ *
+ * 关键点（中文）
+ * - pipeline 变换值，guard 抛错即中断，effect 只产生副作用。
+ * - 没有处理器时返回原值，调用方不需要判断检查点是否存在。
+ * - 处理器失败不向上抛出：内容贡献是增强，不应阻断 Session 主链路。
+ */
+
+import type {
+  EffectHook,
+  GuardHook,
+  JsonValue,
+  PipelineHook,
+  ToolCallContext,
+  ToolHookSet,
+} from "@downcity/type";
+
+/** 单个检查点执行失败时的观察入口。 */
+export type HookFailureObserver = (
+  point_name: string,
+  error: unknown,
+) => Promise<void>;
+
+/** 运行一个 pipeline 检查点；处理器按顺序链式变换值。 */
+export async function run_pipeline_point<TValue extends JsonValue>(input: {
+  /** 当前生效的处理器集合。 */
+  readonly hooks: ToolHookSet;
+  /** 目标检查点名。 */
+  readonly point_name: string;
+  /** 当前值。 */
+  readonly value: TValue;
+  /** 当前调用环境。 */
+  readonly context: ToolCallContext;
+  /** 失败观察入口。 */
+  readonly on_error?: HookFailureObserver;
+}): Promise<TValue> {
+  const handlers = input.hooks.pipeline[input.point_name] as unknown as
+    | readonly PipelineHook<TValue>[]
+    | undefined;
+  if (!handlers || handlers.length === 0) return input.value;
+  let current = input.value;
+  for (const handler of handlers) {
+    try {
+      current = await handler(current, input.context);
+    } catch (error) {
+      await input.on_error?.(input.point_name, error);
+    }
+  }
+  return current;
+}
+
+/** 运行一个 guard 检查点；任一处理器抛错即中断。 */
+export async function run_guard_point(input: {
+  /** 当前生效的处理器集合。 */
+  readonly hooks: ToolHookSet;
+  /** 目标检查点名。 */
+  readonly point_name: string;
+  /** 当前值。 */
+  readonly value: JsonValue;
+  /** 当前调用环境。 */
+  readonly context: ToolCallContext;
+}): Promise<void> {
+  const handlers = input.hooks.guard[input.point_name] as unknown as
+    | readonly GuardHook[]
+    | undefined;
+  if (!handlers || handlers.length === 0) return;
+  for (const handler of handlers) {
+    await handler(input.value, input.context);
+  }
+}
+
+/** 运行一个 effect 检查点；失败被隔离，不影响后续处理器与主链路。 */
+export async function run_effect_point(input: {
+  /** 当前生效的处理器集合。 */
+  readonly hooks: ToolHookSet;
+  /** 目标检查点名。 */
+  readonly point_name: string;
+  /** 当前值。 */
+  readonly value: JsonValue;
+  /** 当前调用环境。 */
+  readonly context: ToolCallContext;
+  /** 失败观察入口。 */
+  readonly on_error?: HookFailureObserver;
+}): Promise<void> {
+  const handlers = input.hooks.effect[input.point_name] as unknown as
+    | readonly EffectHook[]
+    | undefined;
+  if (!handlers || handlers.length === 0) return;
+  for (const handler of handlers) {
+    try {
+      await handler(input.value, input.context);
+    } catch (error) {
+      await input.on_error?.(input.point_name, error);
+    }
+  }
+}

package/src/session/{SessionSystem.ts → input/SessionSystem.ts}

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 面向 `Agent` SDK 的本地会话执行场景。
- * - 注入调用方显式传入的静态 instruction 与 Plugin system blocks。
+ * - 注入调用方显式传入的静态 instruction 与 Power system blocks。
  * - SDK 不在 system 中注入动态变量；动态上下文应由调用方放入 user message。
  */
 
@@ -13,10 +13,11 @@ import type {
 } from "@/types/agent/SessionTypes.js";
 import type {
   BuildSessionSystemBlocksInput,
-  ResolveSessionPluginSystemBlocksInput,
+  ResolveSessionPowerSystemBlocksInput,
 } from "@/types/session/SessionSystem.js";
 import type { JsonValue, SessionSystemContextHookValue } from "@downcity/type";
-import { SESSION_HOOK_POINTS } from "@/session/SessionHookPoints.js";
+import { SESSION_HOOK_POINTS } from "@downcity/type";
+import { run_pipeline_point } from "@/session/input/SessionHookRunner.js";
 
 function normalize_system_blocks(
   blocks: AgentSessionSystemBlock[],
@@ -30,7 +31,7 @@ function normalize_system_blocks(
       if (
         source !== "core" &&
         source !== "instruction" &&
-        source !== "plugin" &&
+        source !== "power" &&
         source !== "session"
       ) {
         return null;
@@ -44,8 +45,8 @@ function normalize_system_blocks(
     .filter((block): block is AgentSessionSystemBlock => Boolean(block));
 }
 
-/** 把 system pipeline 输出限制为稳定的 Plugin 命名内容块。 */
-export function normalize_plugin_system_blocks(
+/** 把 system pipeline 输出限制为稳定的 Power 命名内容块。 */
+export function normalize_power_system_blocks(
   input: unknown,
 ): AgentSessionSystemBlock[] {
   if (!Array.isArray(input)) return [];
@@ -55,37 +56,39 @@ export function normalize_plugin_system_blocks(
     const name = String(record.name || "").trim();
     const content = String(record.content || "").trim();
     if (!name || !content) return [];
-    return [{ source: "plugin" as const, name, content }];
+    return [{ source: "power" as const, name, content }];
   });
 }
 
-/** 使用统一 Hook 检查点解析当前 Session 的 Plugin system blocks。 */
-export async function resolve_session_plugin_system_blocks(
-  input: ResolveSessionPluginSystemBlocksInput,
+/**
+ * 使用统一检查点解析当前 Session 的扩展 system blocks。
+ *
+ * 关键点（中文）
+ * - 只有一个入口：`session.system_context` pipeline。扩展能力不再有独立的
+ *   `system()` 通道，因此不需要判断「静态说明写哪里」。
+ * - 处理器失败降级为空集合，不阻断 Session 主链路。
+ */
+export async function resolve_session_power_system_blocks(
+  input: ResolveSessionPowerSystemBlocksInput,
 ): Promise<AgentSessionSystemBlock[]> {
-  let blocks: AgentSessionSystemBlock[];
-  try {
-    blocks = normalize_plugin_system_blocks(
-      await input.hooks.system_blocks(input.context),
-    );
-  } catch (error) {
-    await input.on_error?.(error);
-    return [];
-  }
   const value: SessionSystemContextHookValue = {
     session_id: input.session_id,
     ...(input.turn_id ? { turn_id: input.turn_id } : {}),
-    blocks,
+    blocks: [],
   };
   try {
-    const output = await input.hooks.pipeline(
-      SESSION_HOOK_POINTS.system_context,
-      value as unknown as JsonValue,
-    ) as unknown as SessionSystemContextHookValue;
-    return normalize_plugin_system_blocks(output?.blocks);
+    const output = await run_pipeline_point({
+      hooks: input.hooks,
+      point_name: SESSION_HOOK_POINTS.system_context,
+      value: value as unknown as JsonValue,
+      context: input.context,
+    });
+    return normalize_power_system_blocks(
+      (output as unknown as SessionSystemContextHookValue)?.blocks,
+    );
   } catch (error) {
     await input.on_error?.(error);
-    return blocks;
+    return [];
   }
 }
 
@@ -110,7 +113,7 @@ function create_session_system_block(
 ): AgentSessionSystemBlock {
   const content = [
     "Current session context:",
-    `You are serving agent "${session.agent_id}" in session "${session.session_id}".`,
+    `This session is "${session.session_id}".`,
     `The current project root is "${session.project_root}".`,
     `This session was created at ${session.created_at}, with ${session.timezone} as its reference timezone.`,
     "This creation time is a stable reference for the session and does not represent the current time for every run.",
@@ -151,8 +154,7 @@ export async function build_session_system_blocks(
   }
   return [
     ...normalize_system_blocks(input.get_instruction_system_blocks()),
-    ...normalize_system_blocks(await input.get_managed_plugin_system_blocks()),
-    ...normalize_system_blocks(await input.get_plugin_system_blocks()),
+    ...normalize_system_blocks(await input.get_power_system_blocks()),
     // session block 放在最后，尽量保留前缀 system blocks 的跨 session 缓存命中。
     create_session_system_block(
       create_session_info({