@southwind-ai/server-sdk 0.1.2 → 0.1.3

package/index.ts

@@ -40,8 +40,19 @@ export type {
   ModuleTaskHandlerRegistration,
   ModuleTaskResult,
 } from "./src/task-registration.js";
+export type {
+  ModuleAgentToolHostPort,
+  ModuleAgentToolInvocation,
+  ModuleAgentToolResult,
+} from "./src/tool-host-port.js";
 export type {
   ModuleToolContext,
   ModuleToolHandlerRegistration,
   ModuleToolResult,
 } from "./src/tool-registration.js";
+export type {
+  ModuleAiJsonValue,
+  ModuleAiOperationContext,
+  ModuleAiOperationHandlerRegistration,
+  ModuleAiOperationPlan,
+} from "./src/ai-operation-registration.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/server-sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -9,6 +9,7 @@
   "files": [
     "index.ts",
     "src/actor.ts",
+    "src/ai-operation-registration.ts",
     "src/audit-port.ts",
     "src/jobs-port.ts",
     "src/module-host.ts",
@@ -19,7 +20,8 @@
     "src/search-provider-port.ts",
     "src/storage-port.ts",
     "src/task-registration.ts",
-    "src/tool-registration.ts"
+    "src/tool-registration.ts",
+    "src/tool-host-port.ts"
   ],
   "scripts": {
     "test": "bun test",

package/src/ai-operation-registration.ts

@@ -0,0 +1,31 @@
+import type { ModuleActor } from "./actor.js";
+
+export type ModuleAiJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | ModuleAiJsonValue[]
+  | { [key: string]: ModuleAiJsonValue };
+
+export interface ModuleAiOperationContext {
+  readonly actor: ModuleActor;
+  readonly requestId: string;
+}
+
+/**
+ * 业务模块只负责把类型化输入收敛为模型无关的指令和用户消息。
+ * Provider、Deployment、Secret、Execution Grant 与 Tool 授权均由宿主持有。
+ */
+export interface ModuleAiOperationPlan {
+  readonly instructions: string;
+  readonly userPrompt: string;
+}
+
+export interface ModuleAiOperationHandlerRegistration {
+  readonly operationKey: string;
+  prepare(
+    input: ModuleAiJsonValue,
+    context: ModuleAiOperationContext,
+  ): Promise<ModuleAiOperationPlan> | ModuleAiOperationPlan;
+}

package/src/module-host.ts

@@ -1,4 +1,5 @@
 import type { DurableHandlerDefinition } from "@southwind-ai/jobs";
+import type { ModuleAiOperationHandlerRegistration } from "./ai-operation-registration.js";
 import type { ModuleRolePreset } from "./role-preset.js";
 import type { ModuleRouteDefinition } from "./route-definition.js";
 import type { ModuleSearchProvider } from "./search-provider-port.js";
@@ -35,6 +36,10 @@ export interface ModuleHost {
   registerToolHandlers(
     registrations: readonly ModuleToolHandlerRegistration[],
   ): void;
+  /** 注册 Manifest `aiOperations` 已声明的模型无关 Operation 执行计划。 */
+  registerAiOperationHandlers(
+    registrations: readonly ModuleAiOperationHandlerRegistration[],
+  ): void;
   /** 注册角色预设；permissionKeys 须属于本模块 Manifest 权限声明。 */
   registerRolePresets(presets: readonly ModuleRolePreset[]): void;
   /** 注册 Manifest `providers` 已声明的搜索 Provider。 */

package/src/tool-host-port.ts

@@ -0,0 +1,22 @@
+import type { ModuleAiJsonValue } from "./ai-operation-registration.js";
+
+export interface ModuleAgentToolInvocation {
+  readonly runId: string;
+  readonly toolCallId: string;
+  readonly toolKey: string;
+  readonly arguments: Readonly<Record<string, ModuleAiJsonValue>>;
+}
+
+export interface ModuleAgentToolResult {
+  readonly value: ModuleAiJsonValue;
+}
+
+/**
+ * 宿主创建并绑定 Operation、Actor 与 Scope 的受限 Tool Host Port。
+ * 调用方不能传 Permission、Feature、License 或数据范围作为授权事实。
+ */
+export interface ModuleAgentToolHostPort {
+  execute(
+    invocation: ModuleAgentToolInvocation,
+  ): Promise<ModuleAgentToolResult>;
+}