@downcity/agent 1.1.337 → 1.1.399

package/src/group/GroupSessions.ts

@@ -0,0 +1,104 @@
+/** GroupSessions：Group 所拥有的可恢复群聊上下文集合。 */
+
+import { nanoid } from "nanoid";
+import { GroupSession } from "@/group/GroupSession.js";
+import type { Group } from "@/group/Group.js";
+import type { WorkspaceBase } from "@downcity/workspace";
+import { get_group_session_store, mark_group_session_started } from "@/internal/GroupRuntime.js";
+import type {
+  GroupSession as GroupSessionContract,
+  GroupSessionCreateInput,
+  GroupSessionGetInput,
+  GroupSessionListInput,
+  GroupSessionSummary,
+  GroupSessions as GroupSessionsContract,
+} from "@/types/group/GroupSession.js";
+
+/** Group 的群聊上下文集合。 */
+export class GroupSessions implements GroupSessionsContract {
+  private readonly group: Group;
+  private readonly sessions_by_id = new Map<string, GroupSession>();
+
+  constructor(group: Group) {
+    this.group = group;
+  }
+
+  /** 创建一个新的群聊上下文，session_id 由内部生成。 */
+  async create(input?: GroupSessionCreateInput): Promise<GroupSessionContract> {
+    const session = this.create_runtime_session(`group-session-${Date.now()}-${nanoid(8)}`, input?.workspace);
+    const store = get_group_session_store(this.group);
+    await session.initialize(store.session(session.id));
+    mark_group_session_started(this.group);
+    this.sessions_by_id.set(session.id, session);
+    return session;
+  }
+
+  /** 恢复当前 Group 的一个群聊上下文。 */
+  async get(session_id: string, input?: GroupSessionGetInput): Promise<GroupSessionContract | null> {
+    const resolved_session_id = String(session_id || "").trim();
+    const cached = this.sessions_by_id.get(resolved_session_id);
+    if (cached) {
+      if (cached.workspace_id !== input?.workspace?.id) {
+        throw new Error(`GroupSession "${resolved_session_id}" is bound to another Workspace`);
+      }
+      return cached;
+    }
+    const store = get_group_session_store(this.group);
+    if (!(await store.has_session(resolved_session_id))) return null;
+    const session = this.create_runtime_session(resolved_session_id, input?.workspace);
+    await session.initialize(store.session(resolved_session_id));
+    mark_group_session_started(this.group);
+    this.sessions_by_id.set(session.id, session);
+    return session;
+  }
+
+  /** 恢复当前 Group 的全部群聊上下文。 */
+  async list(input?: GroupSessionListInput): Promise<readonly GroupSessionSummary[]> {
+    const store = get_group_session_store(this.group);
+    const metadata = await store.list_session_metadata();
+    if (metadata.length > 0) mark_group_session_started(this.group);
+    const workspace_id = String(input?.workspace_id || "").trim() || undefined;
+    const filtered_metadata = workspace_id
+      ? metadata.filter((item) => item.workspace_id === workspace_id)
+      : metadata;
+    return filtered_metadata.map((item) => ({
+      id: item.session_id,
+      group_id: item.group_id,
+      created_at: item.created_at,
+      updated_at: item.updated_at,
+      message_count: item.message_count,
+      ...(item.workspace_id ? { workspace_id: item.workspace_id } : {}),
+      ...(item.preview_text ? { preview_text: item.preview_text } : {}),
+    }));
+  }
+
+  /** 释放并删除指定群聊上下文及其持久化数据。 */
+  async remove(session_id: string, input?: GroupSessionGetInput): Promise<GroupSessionContract | null> {
+    const resolved_session_id = String(session_id || "").trim();
+    const session = await this.get(resolved_session_id, input);
+    if (!session) return null;
+    await session.dispose();
+    await get_group_session_store(this.group).remove_session(resolved_session_id);
+    this.sessions_by_id.delete(resolved_session_id);
+    return session;
+  }
+
+  /** 释放 Group 所有群聊上下文。 */
+  async dispose(): Promise<void> {
+    await Promise.allSettled([...this.sessions_by_id.values()].map((session) => session.dispose()));
+    this.sessions_by_id.clear();
+    await get_group_session_store(this.group).dispose();
+  }
+
+  private create_runtime_session(session_id: string, workspace?: WorkspaceBase): GroupSession {
+    return new GroupSession({
+      id: session_id,
+      group_id: this.group.id,
+      group_name: this.group.name,
+      instruction: this.group.instruction,
+      members: this.group.members,
+      dispatch_strategy: this.group.dispatch_strategy,
+      ...(workspace ? { workspace } : {}),
+    });
+  }
+}

package/src/group/index.ts

@@ -0,0 +1,29 @@
+/** Group 主体公开入口。 */
+export { Group } from "./Group.js";
+export { GroupSession } from "./GroupSession.js";
+export { GroupSessions } from "./GroupSessions.js";
+export { AiDispatchStrategy } from "@/types/group/DispatchStrategy.js";
+export type {
+  DispatchDecision,
+  DispatchNode,
+  DispatchResponseMode,
+  DispatchTrigger,
+  DispatchStrategy,
+  AiDispatchStrategyOptions,
+} from "@/types/group/DispatchStrategy.js";
+export type { GroupContract, GroupMessage, GroupOptions } from "@/types/group/Group.js";
+export type {
+  GroupMemberRuntime,
+  GroupEvent,
+  GroupStatusPhase,
+  GroupEventSubscriber,
+  GroupEventUnsubscribe,
+  GroupPromptInput,
+  GroupPromptResult,
+  GroupSessionContract,
+  GroupSessionCreateInput,
+  GroupSessionGetInput,
+  GroupSessionListInput,
+  GroupSessionSummary,
+  GroupSessions as GroupSessionsContract,
+} from "@/types/group/GroupSession.js";

package/src/index.ts

@@ -3,46 +3,99 @@
  *
  * 关键点（中文）
  * - 这是 agent 包核心运行时的稳定公开入口；可选 Tool 通过 `@downcity/agent/tools` 导出。
- * - 只导出 Agent、plugin 作者 API、city 运行集成 API 与跨包协议类型。
+ * - 只导出 Agent、plugin 作者 API 与跨包协议类型。
  * - HTTP router、sandbox runner、内部 plugin runtime runner 等实现细节不从根入口暴露。
  */
 
 // Agent 入口
 export { Agent } from "./agent/Agent.js";
-export { Workspace } from "./workspace/Workspace.js";
-export { WorkspaceBase } from "./workspace/WorkspaceBase.js";
-export type { AgentStore } from "./types/store/AgentStore.js";
+export { Group } from "./group/Group.js";
+export type {
+  DispatchDecision,
+  DispatchNode,
+  DispatchResponseMode,
+  DispatchTrigger,
+  DispatchStrategy,
+  AiDispatchStrategyOptions,
+  GroupContract,
+  GroupMessage,
+  GroupOptions,
+} from "./group/index.js";
+export type {
+  GroupSessionDataStore,
+  GroupSessionHistoryMeta,
+  GroupSessionStore,
+} from "./types/group/GroupSessionStore.js";
+export { GroupSession, GroupSessions } from "./group/index.js";
+export type {
+  GroupMemberRuntime,
+  GroupEvent,
+  GroupStatusPhase,
+  GroupEventSubscriber,
+  GroupEventUnsubscribe,
+  GroupPromptInput,
+  GroupPromptResult,
+  GroupSessionContract,
+  GroupSessionCreateInput,
+  GroupSessionGetInput,
+  GroupSessionListInput,
+  GroupSessionSummary,
+  GroupSessionsContract,
+} from "./group/index.js";
+export { AiDispatchStrategy } from "./group/index.js";
+export { City } from "./city/index.js";
+export type {
+  CityAgents,
+  CityGroups,
+  CityListenOptions,
+  CityOptions,
+  CityRuntimeOptions,
+  CityWorkspaces,
+} from "./city/index.js";
+export type {
+  PluginHostContext,
+  PluginHostExtensions,
+  AgentPluginModule,
+} from "./city/index.js";
+export {
+  create_city_host_instance_id,
+  get_city_host_state_path,
+  is_process_alive,
+  read_city_host_state,
+  register_city_host,
+  request_city_host_shutdown,
+  unregister_city_host,
+  wait_for_city_host_exit,
+} from "./city/index.js";
+export type {
+  AgentHttpBinding,
+  AgentHttpListenOptions,
+  AgentHttpRuntimeOptions,
+  CityHttpRuntimeOptions,
+  CityAgentHttpExtension,
+  AgentRpcBinding,
+  AgentRpcListenOptions,
+  AgentRpcRuntimeOptions,
+  CityRpcRuntimeOptions,
+  AgentSessionModelResolver,
+  CityHostOwner,
+  CityHostState,
+} from "./city/index.js";
+export type { SessionStore } from "./types/store/SessionStore.js";
 export type {
   CompactActiveMessagesInput,
   CompactActiveMessagesResult,
   SessionMessageCommitState,
   SessionMessageStore,
-  SessionStore,
-} from "./types/store/SessionStore.js";
+  SessionDataStore,
+} from "./types/store/SessionDataStore.js";
 export type { SessionAttachmentStore } from "./types/store/SessionAttachmentStore.js";
 export { create_session_message_store } from "./workspace/store/SessionMessageStoreFactory.js";
-export type {
-  FileSystem,
-  WorkspaceDirectoryEntry,
-} from "./types/workspace/FileSystem.js";
-export type {
-  FileToolActionRequest,
-  FileToolActionResult,
-} from "./types/workspace/FileTool.js";
-export type {
-  SearchToolActionRequest,
-  SearchToolActionResult,
-} from "./types/workspace/SearchTool.js";
-export type { WorkspaceOptions } from "./types/workspace/Workspace.js";
-export type {
-  WorkspaceEnvPatch,
-  WorkspaceEnvSubscriber,
-  WorkspaceEnvUnsubscribe,
-} from "./types/workspace/WorkspaceEnv.js";
-export type { WorkspaceTools } from "./types/workspace/WorkspaceTools.js";
+export type { AgentStorage } from "./types/agent/AgentStorage.js";
 export { RemoteAgent } from "./remote/RemoteAgent.js";
 export { Session } from "./session/Session.js";
 export type { SessionOptions } from "./types/session/SessionOptions.js";
+export type { SessionOrigin } from "./types/session/SessionOrigin.js";
 export {
   infer_agent_model_label,
   normalize_agent_model,
@@ -78,16 +131,13 @@ export type {
   ListSessionMessagesInput,
   SessionActionMessage,
   SessionAssistantDataPart,
-  SessionAssistantDocumentSourcePart,
   SessionAssistantFilePart,
   SessionAssistantInteractionPart,
   SessionAssistantMessage,
   SessionAssistantMessagePart,
-  SessionAssistantSourcePart,
-  SessionAssistantStepPart,
+  SessionAssistantReasoningPart,
   SessionAssistantTextPart,
   SessionAssistantToolPart,
-  SessionAssistantUrlSourcePart,
   SessionErrorMessage,
   SessionMessage,
   SessionMessagePage,
@@ -111,6 +161,7 @@ export {
 } from "./types/session/SessionMutation.js";
 export type {
   SessionCompactMutation,
+  SessionConfigMutation,
   SessionDeltaMutation,
   SessionMessageMutation,
   SessionMutation,
@@ -118,12 +169,11 @@ export type {
   SessionMutationUnsubscribe,
   SessionPartMutation,
   SessionStateMutation,
+  SessionTitleMutation,
   SessionTurnMutation,
 } from "./types/session/SessionMutation.js";
 export type {
   RespondSessionInteractionInput,
-  SessionApprovalInteractionRequest,
-  SessionApprovalInteractionResponse,
   SessionApprovalMode,
   SessionCancelledInteractionResult,
   SessionExpiredInteractionResult,
@@ -140,16 +190,16 @@ export type {
   SessionInteractionSource,
   SessionInteractionStatus,
   SessionPendingInteraction,
-  SessionQuestionInteractionRequest,
-  SessionQuestionInteractionResponse,
   SessionResolvedInteractionResult,
-  SessionShellApprovalInteractionRequest,
-  SessionToolApprovalInteractionRequest,
 } from "./types/session/SessionInteraction.js";
 export type {
   AgentOptions,
   AgentSessionConstructor,
 } from "./types/agent/AgentOptions.js";
+export type {
+  AgentCreateSessionOptions,
+  AgentSessionCollection,
+} from "./types/agent/AgentSessionCollection.js";
 export type {
   AgentSession,
   AgentSessionActor,
@@ -169,6 +219,13 @@ export type {
   AgentSessionActionState,
 } from "./types/sdk/AgentSessionAction.js";
 export type { AgentSessionPromptInput } from "./types/sdk/AgentSessionPrompt.js";
+export type {
+  SessionPromptPart,
+  SessionAssistantResultPart,
+  SessionTextInputPart,
+  SessionFileInputPart,
+  SessionDataInputPart,
+} from "./types/session/SessionContent.js";
 export type { AgentSessionStopResult } from "./types/sdk/AgentSessionStop.js";
 export type {
   AgentSessionTurnHandle,
@@ -180,6 +237,10 @@ export type {
   AgentSessionCompactResult,
 } from "./types/sdk/AgentSessionCompact.js";
 export type { PluginContext } from "./types/plugin/PluginContext.js";
+export type { AgentPluginContext } from "./types/plugin/AgentPluginContext.js";
+export type {
+  PluginWebServices,
+} from "./types/plugin/PluginServices.js";
 export type { SessionPort } from "./types/session/SessionPort.js";
 
 // Plugin 作者 API
@@ -225,7 +286,6 @@ export type {
 export { DefaultSessionSystemComposer } from "./executor/composer/system/default/DefaultSessionSystemComposer.js";
 export { resolve_session_system_messages } from "./executor/composer/system/default/SystemDomain.js";
 export type {
-  SessionAssistantStepCallback,
   SessionExecutor,
   SessionTurnExecutionResult,
 } from "./types/session/SessionExecution.js";
@@ -236,17 +296,16 @@ export type {
 } from "./types/executor/SessionTurnContext.js";
 export type { SessionToolExecutionContext } from "./types/executor/SessionToolExecutionContext.js";
 export type { PluginExecutionContext } from "./types/plugin/PluginExecutionContext.js";
+export type { PluginActionExecutionContext } from "./types/plugin/PluginActionExecution.js";
 export type {
-  SessionActionRecordV1,
-  SessionMessageRecordV1,
-  SessionMetadataV1,
-  SessionRecordV1,
-  SessionUserMessageV1,
-} from "./executor/types/SessionRecords.js";
-export {
-  is_session_action_record,
-  is_session_message_record,
-} from "./executor/types/SessionRecords.js";
+  ToolActionExecutionContext,
+  ToolSessionExecutionScope,
+} from "./types/tools/ToolActionExecutionContext.js";
+export type {
+  SessionActionEvent,
+  SessionActionEventInput,
+  SessionActionStatus,
+} from "./types/session/SessionAction.js";
 export type { SessionSystemMessage } from "./executor/types/SessionPrompts.js";
 export { transform_prompts_into_system_messages } from "./executor/composer/system/default/PromptRenderer.js";
 // 通用 plugin 宿主工具
@@ -269,10 +328,11 @@ export {
 export { ActionScheduleStore } from "./plugin/core/ActionScheduleStore.js";
 export { parse_action_schedule_run_at_ms_or_throw } from "./plugin/core/ActionScheduleTime.js";
 export {
-  pick_last_successful_chat_send_text,
-  resolve_assistant_message_for_persistence,
-} from "./executor/messages/UserVisibleText.js";
-export { extract_tool_calls_from_ui_message } from "./executor/messages/UIMessageTransformer.js";
+  extract_session_message_text,
+  extract_session_tool_calls,
+  resolve_session_assistant_visible_text,
+} from "./session/messages/SessionMessageText.js";
+export type { SessionToolCallSummary } from "./session/messages/SessionMessageText.js";
 export {
   build_chat_message_text,
   parse_chat_message_markup,
@@ -285,12 +345,6 @@ export type {
   ChatMessageSendOptions,
 } from "./executor/messages/ChatMessageMarkupTypes.js";
 
-// Workspace 环境集成
-export {
-  load_project_dotenv,
-  resolve_workspace_env,
-} from "./workspace/WorkspaceEnv.js";
-
 // 日志
 export { get_logger, type Logger } from "./utils/logger/Logger.js";
 export { generate_id } from "./utils/Id.js";
@@ -350,10 +404,6 @@ export type {
   PluginActionScheduleInput,
 } from "./plugin/types/ActionSchedule.js";
 export { list_plugin_states } from "./plugin/core/PluginStateController.js";
-export {
-  invoke_plugin_action,
-  resolve_plugin_action,
-} from "./plugin/core/PluginActionRunner.js";
 
 // 跨包 RPC 与 session 标识协议
 export type {

package/src/internal/AgentRuntime.ts

@@ -0,0 +1,229 @@
+/**
+ * Agent 内部运行时协议。
+ *
+ * 这些函数只供 City、transport 与 Agent 自身使用。它们承载 Agent 与
+ * Workspace 的运行时关系，但不把执行作用域提升为 Agent 的公开领域 API。
+ */
+import { Agent } from "@/agent/Agent.js";
+import { WorkspaceEntry } from "@/agent/WorkspaceEntry.js";
+import type { WorkspaceBase } from "@downcity/workspace";
+import type { City } from "../city/index.js";
+import type { Embassy } from "@downcity/federation";
+import type { StorageProvider, StorageScope } from "@downcity/workspace";
+import { MemoryStorageProvider } from "@downcity/workspace";
+import type { AgentStorage } from "@/types/agent/AgentStorage.js";
+import { LocalSessionStore } from "@/workspace/store/LocalSessionStore.js";
+import {
+  start_action_schedule_runtime,
+  type ActionScheduleRuntimeHandle,
+} from "@/plugin/core/ActionScheduleRuntime.js";
+
+interface AgentRuntimeState {
+  bound_city?: City;
+  embassy?: Embassy;
+  memory_session_started?: boolean;
+  workspaces_by_id: Map<string, WorkspaceEntry>;
+  storage_provider: StorageProvider;
+  agent_storage?: AgentStorage;
+  action_schedule?: ActionScheduleRuntimeHandle;
+  action_schedule_promise?: Promise<void>;
+}
+
+const runtime_states = new WeakMap<Agent, AgentRuntimeState>();
+/** 未加入 City 的 Workspace 只允许一个 Agent 建立执行作用域。 */
+const unbound_workspace_owners = new WeakMap<object, Agent>();
+
+export function initialize_agent_runtime(agent: Agent): void {
+  runtime_states.set(agent, {
+    workspaces_by_id: new Map(),
+    storage_provider: new MemoryStorageProvider(),
+  });
+}
+
+function runtime_state(agent: Agent): AgentRuntimeState {
+  const state = runtime_states.get(agent);
+  if (!state) throw new Error(`Agent "${agent.id}" runtime is not initialized`);
+  return state;
+}
+
+export function attach_agent_city(agent: Agent, city: City): void {
+  const state = runtime_state(agent);
+  if (state.memory_session_started) {
+    throw new Error(
+      `Agent "${agent.id}" already created Session data without City; join City before creating Sessions`,
+    );
+  }
+  if (state.bound_city && state.bound_city !== city) {
+    throw new Error(`Agent "${agent.id}" already belongs to another City`);
+  }
+  state.bound_city = city;
+  state.embassy = city.embassy;
+}
+
+/** 将 City 提供的底层 Storage 注入 Agent；该函数只在组合根调用。 */
+export function attach_agent_storage(agent: Agent, storage_provider: StorageProvider): void {
+  const state = runtime_state(agent);
+  if (state.memory_session_started) {
+    throw new Error(
+      `Agent "${agent.id}" already created Session data without City; join City before creating Sessions`,
+    );
+  }
+  if (state.agent_storage) {
+    throw new Error(`Agent "${agent.id}" storage is already initialized`);
+  }
+  state.storage_provider = storage_provider;
+}
+
+/** 标记 Agent 已经创建或恢复过无 City 的 Session。 */
+export function mark_agent_session_started(agent: Agent): void {
+  const state = runtime_state(agent);
+  if (!state.bound_city) state.memory_session_started = true;
+}
+
+export function detach_agent_city(agent: Agent, city: City): void {
+  const state = runtime_state(agent);
+  if (state.bound_city === city) {
+    state.bound_city = undefined;
+    state.embassy = undefined;
+  }
+}
+
+export function agent_is_in_city(agent: Agent): boolean {
+  return Boolean(runtime_state(agent).bound_city);
+}
+
+/** 返回 City 注入的窄 Embassy 能力。 */
+export function agent_embassy(agent: Agent): Embassy | undefined {
+  return runtime_state(agent).embassy;
+}
+
+/** 由 Agent 释放自身时通知所属 City。 */
+export function release_agent_from_city(agent: Agent): void {
+  runtime_state(agent).bound_city?.release_agent(agent);
+}
+
+/** 返回 Agent 解释出的业务存储作用域。 */
+export function agent_storage_scope(agent: Agent): StorageScope {
+  return runtime_state(agent).storage_provider.open_scope(["agents", agent.id]);
+}
+
+/** 返回指定 Agent Plugin 的底层数据作用域。 */
+export function plugin_storage_scope(agent: Agent, plugin_id: string): StorageScope {
+  return runtime_state(agent).storage_provider.open_scope([
+    "agents",
+    agent.id,
+    "plugins",
+    plugin_id,
+  ]);
+}
+
+/** 获取或创建 Agent 唯一的 Session 存储。 */
+export function get_agent_storage(
+  agent: Agent,
+): AgentStorage {
+  const state = runtime_state(agent);
+  if (state.agent_storage) return state.agent_storage;
+  const scope = state.storage_provider.open_scope(["agents", agent.id]);
+  const files = scope.files;
+  const storage: AgentStorage = {
+    root_path: scope.root_path,
+    files,
+    sessions: new LocalSessionStore({
+      files,
+      storage_root_path: scope.root_path,
+      agent_id: agent.id,
+    }),
+  };
+  state.agent_storage = storage;
+  return storage;
+}
+
+/** 启动 Agent 唯一的 ActionSchedule 轮询器；重复调用共享同一个启动 Promise。 */
+export function ensure_agent_action_schedule(agent: Agent): void {
+  const state = runtime_state(agent);
+  if (state.action_schedule || state.action_schedule_promise) return;
+  const storage = state.agent_storage;
+  if (!storage) return;
+  state.action_schedule_promise = (async () => {
+    await agent.ensure_ready();
+    const handle = await start_action_schedule_runtime(
+      agent.id,
+      storage,
+      agent.get_logger(),
+      (workspace_id) => {
+        const state = runtime_state(agent);
+        if (workspace_id) return state.workspaces_by_id.get(workspace_id)?.get_context() || null;
+        return state.workspaces_by_id.values().next().value?.get_context() || null;
+      },
+    );
+    state.action_schedule = handle;
+  })().catch((error) => {
+    agent.get_logger().error(`ActionSchedule start failed: ${String(error)}`);
+  });
+}
+
+/** 停止 Agent 级后台资源并释放 Agent 级 Store。 */
+export async function dispose_agent_runtime(agent: Agent): Promise<void> {
+  const state = runtime_state(agent);
+  await state.action_schedule_promise?.catch(() => undefined);
+  state.action_schedule?.stop();
+  state.action_schedule = undefined;
+  state.action_schedule_promise = undefined;
+  await state.agent_storage?.sessions.dispose();
+  state.agent_storage = undefined;
+}
+
+/** 返回 Agent 已装配的唯一存储；未装配时返回 null。 */
+export function agent_storage(agent: Agent): AgentStorage | null {
+  return runtime_state(agent).agent_storage ?? null;
+}
+
+export function create_workspace_entry(agent: Agent, workspace: WorkspaceBase): WorkspaceEntry {
+  const state = runtime_state(agent);
+  const workspace_id = String(workspace?.id || "").trim();
+  if (!workspace_id) throw new Error("Agent sessions require a Workspace with a stable id");
+  const city = state.bound_city;
+  if (city && city.get_workspace(workspace_id) !== workspace) {
+    throw new Error(`Workspace "${workspace_id}" does not belong to the Agent City`);
+  }
+  if (!city) {
+    const owner = unbound_workspace_owners.get(workspace);
+    if (owner && owner !== agent) {
+      throw new Error(`Workspace "${workspace_id}" already bound to another scope`);
+    }
+    unbound_workspace_owners.set(workspace, agent);
+  }
+  const existing = state.workspaces_by_id.get(workspace_id);
+  if (existing) {
+    if (existing.workspace !== workspace) {
+      throw new Error(`Agent already entered Workspace "${workspace_id}" with another instance`);
+    }
+    return existing;
+  }
+  const entry = new WorkspaceEntry({ agent, workspace });
+  state.workspaces_by_id.set(workspace_id, entry);
+  ensure_agent_action_schedule(agent);
+  return entry;
+}
+
+export function get_workspace_entry(agent: Agent, workspace_id_input: string): WorkspaceEntry | null {
+  return runtime_state(agent).workspaces_by_id.get(String(workspace_id_input || "").trim()) ?? null;
+}
+
+export function list_workspace_entries(agent: Agent): readonly WorkspaceEntry[] {
+  return [...runtime_state(agent).workspaces_by_id.values()];
+}
+
+export function release_workspace_entry(agent: Agent, workspace_id: string, entry: WorkspaceEntry): void {
+  const state = runtime_state(agent);
+  if (state.workspaces_by_id.get(workspace_id) === entry) {
+    state.workspaces_by_id.delete(workspace_id);
+    if (!state.bound_city && unbound_workspace_owners.get(entry.workspace) === agent) {
+      unbound_workspace_owners.delete(entry.workspace);
+    }
+  }
+}
+
+export function clear_agent_runtime(agent: Agent): void {
+  runtime_states.delete(agent);
+}