@downcity/agent 1.1.337 → 1.1.399

package/src/internal/GroupRuntime.ts

@@ -0,0 +1,89 @@
+/** Group 内部运行时：连接 Group 与 City 提供的底层 Storage。 */
+
+import type { Group } from "@/group/Group.js";
+import type { GroupSessionStore } from "@/types/group/GroupSessionStore.js";
+import type { StorageProvider } from "@downcity/workspace";
+import { MemoryStorageProvider } from "@downcity/workspace";
+import { LocalGroupSessionStore } from "@/workspace/store/LocalGroupSessionStore.js";
+
+interface GroupRuntimeState {
+  /** Group 当前绑定的底层 Storage Provider。 */
+  storage_provider: StorageProvider;
+  /** Group 是否已经创建过无 City 的内存 Session。 */
+  memory_session_started?: boolean;
+  /** Group 是否已经绑定到 City 提供的 Storage。 */
+  storage_attached?: boolean;
+  /** 当前 Group 所属的 City 运行时实例。 */
+  owner?: object;
+  /** GroupSession 集合持久化 Store。 */
+  group_session_store?: GroupSessionStore;
+}
+
+const runtime_states = new WeakMap<Group, GroupRuntimeState>();
+
+/** 初始化 Group 内部运行时，并默认使用内存 Storage。 */
+export function initialize_group_runtime(group: Group): void {
+  runtime_states.set(group, { storage_provider: new MemoryStorageProvider() });
+}
+
+/** 将 City 提供的 Storage 绑定到 Group。 */
+export function attach_group_storage(group: Group, storage_provider: StorageProvider, owner?: object): void {
+  const state = require_group_runtime(group);
+  if (state.memory_session_started) {
+    throw new Error(
+      `Group "${group.id}" already created Session data without City; join City before creating GroupSessions`,
+    );
+  }
+  if (state.owner && owner && state.owner !== owner) {
+    throw new Error(`Group "${group.id}" already belongs to another City`);
+  }
+  state.storage_provider = storage_provider;
+  state.storage_attached = true;
+  state.owner = owner;
+  state.group_session_store = undefined;
+}
+
+/** 解除 Group 与 City Storage 的绑定，允许主体重新装配到其他 City。 */
+export async function detach_group_storage(group: Group, owner?: object): Promise<void> {
+  const state = require_group_runtime(group);
+  if (owner && state.owner && state.owner !== owner) return;
+  await state.group_session_store?.dispose();
+  state.group_session_store = undefined;
+  state.storage_provider = new MemoryStorageProvider();
+  state.storage_attached = false;
+  state.owner = undefined;
+}
+
+/** 获取 Group 的 GroupSession 持久化 Store。 */
+export function get_group_session_store(group: Group): GroupSessionStore {
+  const state = require_group_runtime(group);
+  if (state.group_session_store) return state.group_session_store;
+  const scope = state.storage_provider.open_scope(["groups", group.id]);
+  state.group_session_store = new LocalGroupSessionStore({
+    files: scope.files,
+    storage_root_path: scope.root_path,
+    group_id: group.id,
+  });
+  return state.group_session_store;
+}
+
+/** 标记 Group 已经创建或恢复过一个 GroupSession。 */
+export function mark_group_session_started(group: Group): void {
+  const state = require_group_runtime(group);
+  if (!state.storage_attached && state.storage_provider instanceof MemoryStorageProvider) {
+    state.memory_session_started = true;
+  }
+}
+
+/** 释放 Group 的 Store 运行时引用。 */
+export async function dispose_group_runtime(group: Group): Promise<void> {
+  const state = require_group_runtime(group);
+  await state.group_session_store?.dispose();
+  state.group_session_store = undefined;
+}
+
+function require_group_runtime(group: Group): GroupRuntimeState {
+  const state = runtime_states.get(group);
+  if (!state) throw new Error(`Group "${group.id}" runtime is not initialized`);
+  return state;
+}

package/src/internal/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @downcity/agent/internal
+ *
+ * Agent 运行时内部协议。应用代码不应依赖此入口；它不属于 SDK 公共领域 API。
+ */
+export {
+  initialize_agent_runtime,
+  attach_agent_city,
+  attach_agent_storage,
+  detach_agent_city,
+  agent_is_in_city,
+  agent_embassy,
+  release_agent_from_city,
+  agent_storage_scope,
+  plugin_storage_scope,
+  get_agent_storage,
+  agent_storage,
+  create_workspace_entry,
+  get_workspace_entry,
+  list_workspace_entries,
+  release_workspace_entry,
+  clear_agent_runtime,
+  dispose_agent_runtime,
+  ensure_agent_action_schedule,
+} from "@/internal/AgentRuntime.js";
+export {
+  initialize_group_runtime,
+  attach_group_storage,
+  detach_group_storage,
+  get_group_session_store,
+  mark_group_session_started,
+  dispose_group_runtime,
+} from "@/internal/GroupRuntime.js";

package/src/plugin/core/ActionScheduleExecutor.ts

@@ -7,15 +7,16 @@
  * - 到期后直接走 Plugin Registry Action 执行入口。
  */
 
-import type { PluginContext } from "@/types/plugin/PluginContext.js";
 import type { ActionScheduleStore } from "@/plugin/core/ActionScheduleStore.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.js";
 
 /**
  * 执行当前已到点的 pending 任务。
  */
 export async function run_due_action_schedule_jobs(params: {
-  context: PluginContext;
   store: ActionScheduleStore;
+  resolve_context: (workspace_id?: string) => PluginContext | null;
+  logger: Pick<PluginContext["logger"], "warn">;
 }): Promise<void> {
   const dueJobs = await params.store.list_due_pending_jobs(Date.now());
   for (const job of dueJobs) {
@@ -23,7 +24,18 @@ export async function run_due_action_schedule_jobs(params: {
     if (!claimed) continue;
 
     try {
-      const result = await params.context.plugins.run_action({
+      const context = params.resolve_context(job.workspace_id);
+      if (!context) {
+        const error = `Workspace "${job.workspace_id}" is not active`;
+        await params.store.mark_job_failed(job.id, error);
+        params.logger.warn("[action-schedule] job failed", {
+          job_id: job.id,
+          workspace_id: job.workspace_id,
+          error,
+        });
+        continue;
+      }
+      const result = await context.plugins.run_action({
         plugin: job.plugin_name,
         action: job.action_name,
         payload: job.payload ?? undefined,
@@ -33,7 +45,7 @@ export async function run_due_action_schedule_jobs(params: {
           job.id,
           result.error || result.message || "scheduled action failed",
         );
-        params.context.logger.warn("[action-schedule] job failed", {
+        params.logger.warn("[action-schedule] job failed", {
           job_id: job.id,
           plugin_name: job.plugin_name,
           action_name: job.action_name,
@@ -45,7 +57,7 @@ export async function run_due_action_schedule_jobs(params: {
       await params.store.mark_job_succeeded(job.id);
     } catch (error) {
       await params.store.mark_job_failed(job.id, String(error));
-      params.context.logger.warn("[action-schedule] job failed", {
+      params.logger.warn("[action-schedule] job failed", {
         job_id: job.id,
         plugin_name: job.plugin_name,
         action_name: job.action_name,

package/src/plugin/core/ActionScheduleRuntime.ts

@@ -7,7 +7,9 @@
  * - 普通 plugin 先启动，ActionSchedule 再开始轮询，避免到期 action 执行到未启动的 plugin。
  */
 
+import type { AgentStorage } from "@/types/agent/AgentStorage.js";
 import type { PluginContext } from "@/types/plugin/PluginContext.js";
+import type { Logger } from "@/utils/logger/Logger.js";
 import { run_due_action_schedule_jobs } from "@/plugin/core/ActionScheduleExecutor.js";
 import { ActionScheduleStore } from "@/plugin/core/ActionScheduleStore.js";
 
@@ -32,12 +34,19 @@ export interface ActionScheduleRuntimeHandle {
  * 启动 ActionSchedule 轮询 runtime。
  */
 export async function start_action_schedule_runtime(
-  context: PluginContext,
+  agent_id: string,
+  storage: AgentStorage,
+  logger: Logger,
+  resolve_context: (workspace_id?: string) => PluginContext | null,
 ): Promise<ActionScheduleRuntimeHandle> {
-  const store = new ActionScheduleStore(context.files);
+  const store = new ActionScheduleStore(
+    storage.files,
+    storage.root_path,
+    agent_id,
+  );
   const recovered = await store.reset_running_jobs_to_pending();
   if (recovered > 0) {
-    context.logger.warn(
+    logger.warn(
       formatActionScheduleLogMessage("Recovered interrupted running jobs"),
       { recovered },
     );
@@ -52,8 +61,9 @@ export async function start_action_schedule_runtime(
     ticking = true;
     try {
       await run_due_action_schedule_jobs({
-        context,
         store,
+        resolve_context,
+        logger,
       });
     } finally {
       ticking = false;
@@ -65,7 +75,7 @@ export async function start_action_schedule_runtime(
     void tick();
   }, ACTION_SCHEDULE_POLL_INTERVAL_MS);
 
-  context.logger.info(formatActionScheduleLogMessage("Runtime started"));
+  logger.info(formatActionScheduleLogMessage("Runtime started"));
 
   return {
     stop: () => {
@@ -76,7 +86,7 @@ export async function start_action_schedule_runtime(
         timer = null;
       }
       store.close();
-      context.logger.info(formatActionScheduleLogMessage("Runtime stopped"));
+      logger.info(formatActionScheduleLogMessage("Runtime stopped"));
     },
   };
 }

package/src/plugin/core/ActionScheduleStore.ts

@@ -15,7 +15,7 @@ import type {
 } from "@/plugin/types/ActionSchedule.js";
 import { generate_id } from "@/utils/Id.js";
 import { get_downcity_schedule_db_path } from "@/workspace/WorkspacePaths.js";
-import type { FileSystem } from "@/types/workspace/FileSystem.js";
+import type { FileSystem } from "@downcity/workspace";
 
 type ActionScheduleJobEvent =
   | {
@@ -76,6 +76,8 @@ function normalizeJobRecord(
 ): ActionScheduleJobRecord {
   return {
     id: String(input.id || "").trim(),
+    agent_id: String(input.agent_id || "").trim(),
+    workspace_id: String(input.workspace_id || "").trim(),
     plugin_name: String(input.plugin_name || "").trim(),
     action_name: String(input.action_name || "").trim(),
     payload: input.payload ?? null,
@@ -136,10 +138,22 @@ export class ActionScheduleStore {
   private readonly file_path: string;
   private readonly lock_path: string;
   private readonly files: FileSystem;
+  private readonly agent_id: string;
+  private readonly default_workspace_id?: string;
 
-  constructor(files: FileSystem) {
+  constructor(
+    files: FileSystem,
+    storage_root_path: string,
+    agent_id: string,
+    default_workspace_id?: string,
+  ) {
     this.files = files;
-    this.file_path = get_downcity_schedule_db_path(files.root_path);
+    this.agent_id = String(agent_id || "").trim();
+    if (!this.agent_id) {
+      throw new Error("ActionScheduleStore requires agent_id");
+    }
+    this.default_workspace_id = String(default_workspace_id || "").trim() || undefined;
+    this.file_path = get_downcity_schedule_db_path(storage_root_path);
     this.lock_path = `${this.file_path}.lock`;
   }
 
@@ -158,6 +172,8 @@ export class ActionScheduleStore {
     const now = Date.now();
     const job: ActionScheduleJobRecord = {
       id: `sched_${generate_id()}`,
+      agent_id: this.agent_id,
+      workspace_id: String(input.workspace_id || this.default_workspace_id || "").trim(),
       plugin_name: String(input.plugin_name || "").trim(),
       action_name: String(input.action_name || "").trim(),
       payload: input.payload ?? null,
@@ -182,9 +198,10 @@ export class ActionScheduleStore {
   async get_job_by_id(job_id: string): Promise<ActionScheduleJobRecord | null> {
     const key = String(job_id || "").trim();
     if (!key) return null;
-    return await this.with_store_lock(async () =>
-      (await this.read_job_map_unlocked()).get(key) || null
-    );
+    return await this.with_store_lock(async () => {
+      const job = (await this.read_job_map_unlocked()).get(key);
+      return job && this.owns_job(job) ? job : null;
+    });
   }
 
   /**
@@ -197,7 +214,7 @@ export class ActionScheduleStore {
     const allowed = new Set(statuses);
     return await this.with_store_lock(async () =>
       (await this.read_jobs_unlocked())
-        .filter((job) => allowed.has(job.status))
+        .filter((job) => this.owns_job(job) && allowed.has(job.status))
         .sort(compareJobs)
     );
   }
@@ -215,7 +232,10 @@ export class ActionScheduleStore {
         : 100;
     return await this.with_store_lock(async () => {
       const jobs = (await this.read_jobs_unlocked())
-        .filter((job) => !params?.status || job.status === params.status)
+        .filter((job) =>
+          this.owns_job(job) &&
+          (!params?.status || job.status === params.status)
+        )
         .sort(compareJobs);
       return jobs.slice(0, limit);
     });
@@ -229,7 +249,9 @@ export class ActionScheduleStore {
       (await this.read_jobs_unlocked())
         .filter(
           (job) =>
-            job.status === "pending" && job.run_at_ms <= Math.trunc(nowMs),
+            this.owns_job(job) &&
+            job.status === "pending" &&
+            job.run_at_ms <= Math.trunc(nowMs),
         )
         .sort(compareJobs)
     );
@@ -241,7 +263,7 @@ export class ActionScheduleStore {
   async reset_running_jobs_to_pending(): Promise<number> {
     return await this.with_store_lock(async () => {
       const running_jobs = (await this.read_jobs_unlocked())
-        .filter((job) => job.status === "running");
+        .filter((job) => this.owns_job(job) && job.status === "running");
       const now = Date.now();
       for (const job of running_jobs) {
         await this.append_event_unlocked({
@@ -346,7 +368,9 @@ export class ActionScheduleStore {
   ): Promise<boolean> {
     return await this.with_store_lock(async () => {
       const current = (await this.read_job_map_unlocked()).get(job_id);
-      if (!current || current.status !== "pending") return false;
+      if (!current || !this.owns_job(current) || current.status !== "pending") {
+        return false;
+      }
       await this.append_event_unlocked({
         v: 1,
         type: "status",
@@ -368,7 +392,9 @@ export class ActionScheduleStore {
   }): Promise<boolean> {
     return await this.with_store_lock(async () => {
       const current = (await this.read_job_map_unlocked()).get(params.job_id);
-      if (!current || current.status !== "running") return false;
+      if (!current || !this.owns_job(current) || current.status !== "running") {
+        return false;
+      }
       await this.append_event_unlocked({
         v: 1,
         type: "status",
@@ -380,4 +406,9 @@ export class ActionScheduleStore {
       return true;
     });
   }
+
+  /** 判断任务是否属于当前 Agent 的调度视图。 */
+  private owns_job(job: ActionScheduleJobRecord): boolean {
+    return job.agent_id === this.agent_id;
+  }
 }

package/src/plugin/core/HookRegistry.ts

@@ -39,7 +39,6 @@ type ResolveRecord = {
  * HookRegistry：plugin 点注册与执行实现。
  */
 export class HookRegistry {
-  private readonly get_context: () => PluginContext;
   private readonly is_plugin_ready: (plugin_name: string) => boolean;
 
   private readonly pipelineHooks = new Map<string, PipelineRecord[]>();
@@ -51,10 +50,8 @@ export class HookRegistry {
   private readonly resolveHooks = new Map<string, ResolveRecord>();
 
   constructor(params: {
-    get_context: () => PluginContext;
     is_plugin_ready: (plugin_name: string) => boolean;
   }) {
-    this.get_context = params.get_context;
     this.is_plugin_ready = params.is_plugin_ready;
   }
 
@@ -199,18 +196,22 @@ export class HookRegistry {
   /**
    * 运行 pipeline 扩展点。
    */
-  async pipelineValue<T = JsonValue>(point_name: string, value: T): Promise<T> {
+  async pipelineValue<T = JsonValue>(
+    context: PluginContext,
+    point_name: string,
+    value: T,
+    resolve_context: (plugin_name: string) => PluginContext = () => context,
+  ): Promise<T> {
     const key = String(point_name || "").trim();
     if (!key) return value;
     const bucket = this.pipelineHooks.get(key) || [];
     if (bucket.length === 0) return value;
 
-    const context = this.get_context();
     let current = value as JsonValue;
     for (const item of bucket) {
       if (!this.is_plugin_ready(item.plugin_name)) continue;
       current = await item.handler({
-        context,
+        context: resolve_context(item.plugin_name),
         value: current,
         plugin: item.plugin_name,
       });
@@ -221,17 +222,21 @@ export class HookRegistry {
   /**
    * 运行 guard 扩展点。
    */
-  async guardValue<T = JsonValue>(point_name: string, value: T): Promise<void> {
+  async guardValue<T = JsonValue>(
+    context: PluginContext,
+    point_name: string,
+    value: T,
+    resolve_context: (plugin_name: string) => PluginContext = () => context,
+  ): Promise<void> {
     const key = String(point_name || "").trim();
     if (!key) return;
     const bucket = this.guardHooks.get(key) || [];
     if (bucket.length === 0) return;
 
-    const context = this.get_context();
     for (const item of bucket) {
       if (!this.is_plugin_ready(item.plugin_name)) continue;
       await item.handler({
-        context,
+        context: resolve_context(item.plugin_name),
         value: value as JsonValue,
         plugin: item.plugin_name,
       });
@@ -241,17 +246,21 @@ export class HookRegistry {
   /**
    * 运行 effect 扩展点。
    */
-  async effectValue<T = JsonValue>(point_name: string, value: T): Promise<void> {
+  async effectValue<T = JsonValue>(
+    context: PluginContext,
+    point_name: string,
+    value: T,
+    resolve_context: (plugin_name: string) => PluginContext = () => context,
+  ): Promise<void> {
     const key = String(point_name || "").trim();
     if (!key) return;
     const bucket = this.effectHooks.get(key) || [];
     if (bucket.length === 0) return;
 
-    const context = this.get_context();
     for (const item of bucket) {
       if (!this.is_plugin_ready(item.plugin_name)) continue;
       await item.handler({
-        context,
+        context: resolve_context(item.plugin_name),
         value: value as JsonValue,
         plugin: item.plugin_name,
       });
@@ -262,8 +271,10 @@ export class HookRegistry {
    * 运行 resolve 点。
    */
   async resolveValue<TInput = JsonValue, TOutput = JsonValue>(
+    context: PluginContext,
     point_name: string,
     value: TInput,
+    resolve_context: (plugin_name: string) => PluginContext = () => context,
   ): Promise<TOutput> {
     const key = String(point_name || "").trim();
     if (!key) {
@@ -273,13 +284,12 @@ export class HookRegistry {
     if (!record) {
       throw new Error(`No plugin resolver registered for point: ${key}`);
     }
-    const context = this.get_context();
     if (!this.is_plugin_ready(record.plugin_name)) {
       throw new Error(`No active plugin resolver registered for point: ${key}`);
     }
 
     return await record.handler({
-      context,
+      context: resolve_context(record.plugin_name),
       value: value as JsonValue,
       plugin: record.plugin_name,
     }) as TOutput;