theokit 0.24.0 → 0.26.0

package/dist/server/index.d.ts

@@ -823,11 +823,16 @@ declare class CodeModePermissionDeniedError extends Error {
     constructor(tool: string, reason?: string);
 }
 /**
- * Build a code-mode `CustomTool`. Fails fast if `onPermissionRequest` or `sandbox` is missing
- * (security by default). The returned tool takes `{ code }`, assembles the permission-gated restricted
- * API from `tools`, runs the code in the injected sandbox, and returns the code's result.
- */
-declare function createCodeMode(config: CodeModeConfig): CustomTool;
+ * Build a code-mode tool + its generated model instructions (M40 / ADR-0049). Fails fast if
+ * `onPermissionRequest` or `sandbox` is missing (security by default). `tool` takes `{ code }`,
+ * assembles the permission-gated restricted API from `tools`, runs the code in the injected sandbox,
+ * and returns the code's result. `instructions` (add it to the agent's system prompt) teaches the
+ * model the sandboxed-code contract + the available `api.<name>(input)` calls.
+ */
+declare function createCodeMode(config: CodeModeConfig): {
+    tool: CustomTool;
+    instructions: string;
+};
 
 /**
  * M27 (ADR-0041) — channel webhook routes: `POST /api/agents/<name>/channels/<platform>/webhook`.

package/dist/server/index.js

@@ -1223,6 +1223,23 @@ var CodeModePermissionDeniedError = class extends Error {
     this.name = "CodeModePermissionDeniedError";
   }
 };
+function describeToolInput(inputSchema) {
+  const props = inputSchema.properties ?? {};
+  const required = new Set(inputSchema.required ?? []);
+  const entries = Object.entries(props).map(([key, spec]) => {
+    const type = typeof spec.type === "string" ? spec.type : "unknown";
+    return `${key}${required.has(key) ? "" : "?"}: ${type}`;
+  });
+  return entries.length > 0 ? `{ ${entries.join(", ")} }` : "{}";
+}
+function generateCodeModeInstructions(tools, toolName) {
+  const calls = tools.map((t) => `- \`await api.${t.name}(${describeToolInput(t.inputSchema)})\` \u2014 ${t.description}`).join("\n");
+  return [
+    `The \`${toolName}\` tool runs your code in a sandbox. Your code may call ONLY these functions (each bridges to a real, validated tool on the host):`,
+    calls,
+    "Write an async function body that composes these calls and return exactly ONE structured result. Prefer `Promise.all` for independent calls; do arithmetic and aggregation in code, not in prose."
+  ].join("\n\n");
+}
 function createCodeMode(config) {
   if (typeof config.onPermissionRequest !== "function") {
     throw new Error(
@@ -1235,16 +1252,22 @@ function createCodeMode(config) {
       "createCodeMode requires an injected `sandbox` with a run() method (a vetted isolation boundary \u2014 never node:vm)."
     );
   }
+  if (config.tools.length === 0) {
+    throw new Error(
+      "createCodeMode requires a non-empty tools[] \u2014 the restricted API would be empty."
+    );
+  }
   const api = {};
-  for (const tool2 of config.tools) {
-    api[tool2.name] = async (args) => {
-      const decision = await config.onPermissionRequest({ tool: tool2.name, args });
-      if (!decision.granted) throw new CodeModePermissionDeniedError(tool2.name, decision.reason);
-      return tool2.handler(args);
+  for (const tool3 of config.tools) {
+    api[tool3.name] = async (args) => {
+      const decision = await config.onPermissionRequest({ tool: tool3.name, args });
+      if (!decision.granted) throw new CodeModePermissionDeniedError(tool3.name, decision.reason);
+      return tool3.handler(args);
     };
   }
-  return {
-    name: config.name ?? "run_code",
+  const name = config.name ?? "run_code";
+  const tool2 = {
+    name,
     description: config.description ?? "Run code that composes the available tools. Only the declared tools are callable.",
     inputSchema: {
       type: "object",
@@ -1257,6 +1280,7 @@ function createCodeMode(config) {
       return typeof result === "string" ? result : JSON.stringify(result);
     }
   };
+  return { tool: tool2, instructions: generateCodeModeInstructions(config.tools, name) };
 }
 
 // src/server/agent/channel-webhook.ts