@springbrand/agent-runtime 0.1.3-alpha.1 → 0.1.3-alpha.10

package/src/tool-registry.ts

@@ -0,0 +1,143 @@
+import type { ExecutionLevel } from "./lib/execution-level";
+import type {
+  RuntimeMemoryPort,
+  WorkspacePort,
+} from "./kernel/bindings";
+import type { RuntimeExtensionConfig } from "./kernel/extensions";
+import type { RuntimeDegradation } from "./kernel/degradation";
+import type { PiToolCandidate } from "./pi/tool/compiler";
+
+/** Tool Surface 筛选策略（不含 Manifest deny 列表）。 */
+export interface ToolSurfaceSelectionPolicy {
+  readonly allowsTool?: (name: string) => boolean;
+  readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
+}
+
+/** 模型调用 Tool 时传给 `execute` 的上下文。 */
+export interface ToolContext {
+  readonly toolCallId: string;
+  readonly signal: AbortSignal;
+}
+
+/** Definition 作者声明的一个 Tool。 */
+export interface ToolSpec {
+  readonly label: string;
+  readonly description: string;
+  readonly parameters: unknown;
+  readonly requiredExecutionLevel: ExecutionLevel;
+  /** Require a fresh human decision for every call, regardless of execution level. */
+  readonly alwaysRequiresApproval?: boolean;
+  readonly execute: (
+    input: unknown,
+    ctx: ToolContext,
+  ) => Promise<unknown>;
+}
+
+/** 一次装配声明的全部 Tool，键即模型可见的工具名。 */
+export type ToolRegistry = Record<string, ToolSpec>;
+
+export function emptyToolRegistry(): ToolRegistry {
+  return {};
+}
+
+export function mergeToolRegistries(...registries: ToolRegistry[]): ToolRegistry {
+  const merged: ToolRegistry = {};
+  for (const registry of registries) {
+    for (const [name, spec] of Object.entries(registry)) {
+      if (name in merged) {
+        throw new Error(`Duplicate Runtime Tool: ${name}`);
+      }
+      merged[name] = spec;
+    }
+  }
+  return merged;
+}
+
+export function toolRegistryFromPiCandidates(
+  candidates:
+    | readonly PiToolCandidate[]
+    | Record<string, PiToolCandidate>,
+): ToolRegistry {
+  const list = Array.isArray(candidates)
+    ? candidates
+    : Object.values(candidates);
+  const registry: ToolRegistry = {};
+  for (const candidate of list) {
+    const name = candidate.tool.name;
+    if (!name.trim()) {
+      throw new Error("Pi Tool name must not be empty");
+    }
+    registry[name] = piCandidateToToolSpec(candidate);
+  }
+  return registry;
+}
+
+export function piCandidateToToolSpec(candidate: PiToolCandidate): ToolSpec {
+  const name = candidate.tool.name;
+  return {
+    label: candidate.tool.label ?? name,
+    description: candidate.tool.description,
+    parameters: candidate.tool.parameters,
+    requiredExecutionLevel: candidate.requiredExecutionLevel,
+    ...(candidate.alwaysRequiresApproval
+      ? { alwaysRequiresApproval: true }
+      : {}),
+    execute: async (input, ctx) => {
+      const execute = candidate.tool.execute;
+      if (typeof execute !== "function") {
+        throw new Error(`Tool "${name}" is not executable`);
+      }
+      const result = await execute(
+        ctx.toolCallId,
+        input,
+        ctx.signal,
+        undefined,
+      );
+      return result.details ?? result;
+    },
+  };
+}
+
+/** Kernel 绑定仍需要的执行后端；不出现在 Definition 公开类型里。 */
+export interface RuntimeToolBindings {
+  readonly workspace?: WorkspacePort;
+  readonly memory?: RuntimeMemoryPort;
+}
+
+/**
+ * Worker `tools()` 可返回纯注册表，或附带 Kernel 绑定与降级信息。
+ */
+export interface ToolAssemblyResult {
+  readonly tools: ToolRegistry;
+  readonly bindings?: RuntimeToolBindings;
+  readonly memoryProfile?: import("./kernel/profile").RuntimeMemoryProfile;
+  readonly enabledSubagents?: readonly string[];
+  readonly degradations?: readonly RuntimeDegradation[];
+  readonly surfacePolicy?: ToolSurfaceSelectionPolicy;
+  readonly commitGuard?: () => Promise<void>;
+  /** 释放本次装配创建的外部资源；临时 Agent 终止后由 Runtime 调用。 */
+  readonly dispose?: () => Promise<void>;
+}
+
+export function normalizeToolAssembly(
+  input: ToolRegistry | ToolAssemblyResult,
+): ToolAssemblyResult {
+  if ("tools" in input && typeof input.tools === "object" && input.tools !== null) {
+    return input as ToolAssemblyResult;
+  }
+  return { tools: input as ToolRegistry };
+}
+
+/** @deprecated 使用 `ToolSpec`。 */
+export type PlatformToolSpec = ToolSpec;
+
+/** @deprecated 使用 `ToolContext`。 */
+export type PlatformToolContext = ToolContext;
+
+/** @deprecated 使用 `ToolRegistry`。 */
+export type PlatformToolRegistry = ToolRegistry;
+
+/** @deprecated 使用 `emptyToolRegistry`。 */
+export function emptyPlatformToolRegistry(): ToolRegistry {
+  return emptyToolRegistry();
+}

package/src/workspace-versioning.ts

@@ -0,0 +1,46 @@
+export type WorkspaceRevision = {
+  revision: string;
+  treeHash: string;
+  reason: string;
+  createdAt: number;
+};
+
+export type WorkspaceRevisionManifest = {
+  revision: string;
+  treeHash: string;
+  files: readonly {
+    path: string;
+    size: number;
+  }[];
+};
+
+export interface WorkspaceVersionPort {
+  current(): Promise<WorkspaceRevision | null>;
+  checkpoint(input: { reason: string }): Promise<{
+    revision: string | null;
+    treeHash: string | null;
+    changed: boolean;
+  }>;
+  list(input?: { limit?: number }): Promise<readonly WorkspaceRevision[]>;
+  manifest(revision: string): Promise<WorkspaceRevisionManifest>;
+  readFile(revision: string, path: string): Promise<Uint8Array>;
+  restore(input: { revision: string; reason: string }): Promise<{
+    revision: string;
+    treeHash: string;
+  }>;
+}
+
+/** Host-scoped restore action exposed to the Agent Runtime. */
+export interface WorkspaceRevisionRestorePort {
+  restore(target: string): Promise<{
+    restoredFrom: string;
+    revision: string;
+    treeHash: string;
+  }>;
+}
+
+export class WorkspaceRevisionNotFoundError extends Error {
+  constructor() {
+    super("workspace_revision_not_found");
+  }
+}