@qilin-agent/tools 3.1.5 → 3.1.6

package/lib/types/py-types.d.ts

@@ -7,7 +7,7 @@
  *
  * Under `mode: 'ptc'` the native tool schemas are omitted from the request, so this generated
  * SDK is the model's ONLY source for each tool's argument names, required fields, types,
- * descriptions, and canonical output shapes. Object-shaped arguments and outputs therefore render as one
+ * descriptions, and canonical output types. Object-shaped arguments and outputs render as one
  * named `TypedDict` per tool (and per nested object), not an opaque `dict[str, Any]`, so the
  * shape survives into the program under the mode that has nothing else to carry it.
  * @module @qilin-agent/tools/src/py-types

package/lib/types/py-types.js

@@ -7,7 +7,7 @@
  *
  * Under `mode: 'ptc'` the native tool schemas are omitted from the request, so this generated
  * SDK is the model's ONLY source for each tool's argument names, required fields, types,
- * descriptions, and canonical output shapes. Object-shaped arguments and outputs therefore render as one
+ * descriptions, and canonical output types. Object-shaped arguments and outputs render as one
  * named `TypedDict` per tool (and per nested object), not an opaque `dict[str, Any]`, so the
  * shape survives into the program under the mode that has nothing else to carry it.
  * @module @qilin-agent/tools/src/py-types
@@ -700,12 +700,12 @@ export function jsonSchemaToPy(schema) {
 /** The fixed model-facing usage contract rendered above the declarations. */
 const SDK_INSTRUCTIONS = `## Writing code for run_code
 
-\`run_code\` takes two required arguments: \`description\`, a short summary of what the program does, and \`code\` — the body of an async Python function (top-level \`await\` and \`return\` both work). At run time exactly two of the names declared below are bound: \`tools\` and \`ToolCallError\`. Everything else is a STATIC STUB describing argument and return types — in particular the \`TypedDict\` classes do NOT exist at run time, so build arguments as plain \`dict\`/\`list\` JSON values: \`await tools.name({"field": 1})\`, never \`FooArgs(field=1)\`, which raises \`NameError\`. Inside the program:
+\`run_code\` takes two required arguments: \`description\`, a short summary of what the program does, and \`code\`, the program to execute. At run time exactly two of the names declared below are bound: \`tools\` and \`ToolCallError\`. Everything else is a STATIC STUB describing argument and return types — in particular the \`TypedDict\` classes do NOT exist at run time, so build arguments as plain \`dict\`/\`list\` JSON values: \`await tools.name({"field": 1})\`, never \`FooArgs(field=1)\`, which raises \`NameError\`. Inside the program:
 
 - Call tools as \`await tools.name(args)\` — subscript access for exotic, reserved, or underscore-leading names: \`await tools["my-tool"](args)\`. Every call resolves to the tool's typed canonical JSON value (each method's return type below). Tool arguments must be lossless JSON.
 - A FAILED tool call raises \`ToolCallError\`, whose \`toolName\` identifies the failed tool and whose message is human-readable — wrap in \`try/except\` to handle and continue.
 - Independent read-only calls MAY overlap under \`asyncio.gather\` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with \`await\`.
-- Emit the run's answer with \`print(...)\` and/or a top-level \`return <value>\`; the returned value must be lossless JSON. Only what you print and return is program output. A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
+- Only values emitted as program output enter the conversation. A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
 
 The available tools:`;
 /**

package/lib/types/ts-types.d.ts

@@ -31,7 +31,8 @@ export declare function jsonSchemaToTs(schema: unknown, indent?: number): string
  * by name, so the input never carries a duplicate.
  * @param schemas - the tool schemas to declare (the caller excludes
  *   `run_code` itself).
+ * @param programFormat - Runtime syntax; function bodies support returning a result, REPLs print it.
  * @returns the complete section text.
  */
-export declare function renderToolsSdk(schemas: ToolSdkSchema[]): string;
+export declare function renderToolsSdk(schemas: ToolSdkSchema[], programFormat?: 'function-body' | 'repl'): string;
 //# sourceMappingURL=ts-types.d.ts.map

package/lib/types/ts-types.js

@@ -218,18 +218,29 @@ export function jsonSchemaToTs(schema, indent = 0) {
         return 'unknown';
     }
 }
-/** The fixed model-facing usage contract rendered above the declarations (see the PTC mode Agent Note's "What the model sees"). */
-const SDK_INSTRUCTIONS = `## Writing code for run_code
+/** Render the argument and call instructions for the selected execution syntax. */
+function renderSdkInstructions(programFormat) {
+    const programDescription = programFormat === 'function-body'
+        ? 'the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped)'
+        : 'the program to execute';
+    return `## Writing code for run_code
 
-\`run_code\` takes two required arguments: \`description\`, a short summary of what the program does, and \`code\` — the body of an async TypeScript function (erasable syntax only — no \`enum\` or namespaces; type annotations are advisory, the code runs type-stripped). The declarations below are SDK bindings for this program. A declaration does not make its name a directly callable tool; only names supplied as separate tool schemas may be called directly.`;
-const SDK_PROGRAM_INSTRUCTIONS = `Inside the program:
+\`run_code\` takes two required arguments: \`description\`, a short summary of what the program does, and \`code\`, ${programDescription}. The declarations below are SDK bindings for this program. A declaration does not make its name a directly callable tool; only names supplied as separate tool schemas may be called directly.`;
+}
+/** Render tool execution and output instructions for the selected execution syntax. */
+function renderSdkProgramInstructions(programFormat) {
+    const outputInstruction = programFormat === 'function-body'
+        ? 'Emit results with `return` and/or `console.log(...)`. Only what you print or return is program output.'
+        : 'Only values emitted as program output enter the conversation.';
+    return `Inside the program:
 
 - Call tools as \`await tools.name(args)\` — quoted access for exotic names: \`tools["my-tool"](args)\`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.
 - A FAILED tool call rejects with \`ToolCallError\`, whose \`toolName\` identifies the failed tool and whose \`message\` is human-readable — \`try/catch\` it to handle and continue.
 - Independent read-only calls MAY overlap under \`Promise.all\` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with \`await\`.
-- Emit results with \`return\` and/or \`console.log(...)\`. Only what you print or return is program output. A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
+- ${outputInstruction} A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
 
 Program-only SDK bindings:`;
+}
 /** Whether one string schema accepts the literal used by the bash example. */
 function acceptsExampleString(schema, value) {
     return schema?.type === 'string'
@@ -237,7 +248,7 @@ function acceptsExampleString(schema, value) {
         && (schema.enum === undefined || schema.enum.includes(value));
 }
 /** Render the bash example only when its literal arguments satisfy the current parameter schema. */
-function renderBashExample(schemas) {
+function renderBashExample(schemas, programFormat) {
     const bash = schemas.find(schema => schema.name === 'bash');
     if (bash === undefined)
         return '';
@@ -253,7 +264,10 @@ function renderBashExample(schemas) {
     if (needsDescription && !acceptsExampleString(parameters.properties?.description, 'Show current directory'))
         return '';
     const description = needsDescription ? "description: 'Show current directory', " : '';
-    return ` When no separate \`bash\` schema is supplied, invoke a declared \`bash\` binding inside \`run_code\`:\n\n\`run_code({ description: "Show current directory", code: "return await tools.bash({ ${description}command: 'pwd' })" })\``;
+    const program = programFormat === 'function-body'
+        ? `return await tools.bash({ ${description}command: 'pwd' })`
+        : `console.log(await tools.bash({ ${description}command: 'pwd' }))`;
+    return ` When no separate \`bash\` schema is supplied, invoke a declared \`bash\` binding inside \`run_code\`:\n\n\`run_code({ description: "Show current directory", code: "${program}" })\``;
 }
 /**
  * Render the full `tools:sdk` prompt section: the fixed usage instructions
@@ -265,9 +279,10 @@ function renderBashExample(schemas) {
  * by name, so the input never carries a duplicate.
  * @param schemas - the tool schemas to declare (the caller excludes
  *   `run_code` itself).
+ * @param programFormat - Runtime syntax; function bodies support returning a result, REPLs print it.
  * @returns the complete section text.
  */
-export function renderToolsSdk(schemas) {
+export function renderToolsSdk(schemas, programFormat = 'function-body') {
     const sorted = [...schemas].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
     const argsMembers = [];
     const outputMembers = [];
@@ -286,6 +301,8 @@ export function renderToolsSdk(schemas) {
         ['declare const tools: {', '  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;', '}'].join('\n'),
     ].join('\n\n');
     const jsonValue = 'type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }';
-    return `${SDK_INSTRUCTIONS}${renderBashExample(sorted)}\n\n${SDK_PROGRAM_INSTRUCTIONS}\n\n\`\`\`ts\n${jsonValue}\n\n${declaration}\n\`\`\``;
+    const instructions = renderSdkInstructions(programFormat);
+    const programInstructions = renderSdkProgramInstructions(programFormat);
+    return `${instructions}${renderBashExample(sorted, programFormat)}\n\n${programInstructions}\n\n\`\`\`ts\n${jsonValue}\n\n${declaration}\n\`\`\``;
 }
 //# sourceMappingURL=ts-types.js.map

package/locale/en.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "tools"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "工具注册与执行",
+    "description": "管理可用工具及其调用执行流程。"
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qilin-agent/tools",
   "description": "Tool registry and execution pipeline for the QiLin",
-  "version": "3.1.5",
+  "version": "3.1.6",
   "publishConfig": {
     "access": "public"
   },
@@ -30,44 +30,46 @@
       "default": "./lib/types/presentation.js"
     },
     "./src/*": "./src/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
   },
   "files": [
+    "locale/*.json",
     "lib/index.js",
     "lib/types/**/*.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/ptc-runtime": "3.1.5",
-    "@qilin-agent/agent": "3.1.5",
-    "@qilin-agent/llm": "3.1.5",
-    "@qilin-agent/system-prompt": "3.1.5",
-    "@qilin-agent/session": "3.1.5",
-    "@qilin-agent/user-approval": "3.1.5",
-    "@qilin-agent/sandbox": "3.1.5",
-    "@qilin-agent/working-directory": "3.1.5",
-    "@qilin-agent/scope": "3.1.5",
-    "@qilin-agent/sandbox-policy": "3.1.5"
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/agent": "3.1.6",
+    "@qilin-agent/ptc-runtime": "3.1.6",
+    "@qilin-agent/llm": "3.1.6",
+    "@qilin-agent/scope": "3.1.6",
+    "@qilin-agent/system-prompt": "3.1.6",
+    "@qilin-agent/session": "3.1.6",
+    "@qilin-agent/user-approval": "3.1.6",
+    "@qilin-agent/sandbox": "3.1.6",
+    "@qilin-agent/working-directory": "3.1.6",
+    "@qilin-agent/sandbox-policy": "3.1.6"
   },
   "dependencies": {
-    "@qilin-agent/brand": "3.1.5",
-    "@qilin-agent/util-values": "3.1.5",
-    "@qilin-agent/schemastery": "~3.18.3"
+    "@qilin-agent/util-values": "3.1.6",
+    "@qilin-agent/schemastery": "~3.18.5",
+    "@qilin-agent/brand": "3.1.6"
   },
   "devDependencies": {
-    "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/agent": "3.1.5",
-    "@qilin-agent/ptc-runtime": "3.1.5",
-    "@qilin-agent/scope": "3.1.5",
-    "@qilin-agent/llm": "3.1.5",
-    "@qilin-agent/session-projection": "3.1.5",
-    "@qilin-agent/system-prompt": "3.1.5",
-    "@qilin-agent/sandbox": "3.1.5",
-    "@qilin-agent/user-approval": "3.1.5",
-    "@qilin-agent/working-directory": "3.1.5",
-    "@qilin-agent/sandbox-policy": "3.1.5",
-    "@qilin-agent/session": "3.1.5"
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/agent": "3.1.6",
+    "@qilin-agent/ptc-runtime": "3.1.6",
+    "@qilin-agent/llm": "3.1.6",
+    "@qilin-agent/scope": "3.1.6",
+    "@qilin-agent/user-approval": "3.1.6",
+    "@qilin-agent/session": "3.1.6",
+    "@qilin-agent/system-prompt": "3.1.6",
+    "@qilin-agent/sandbox": "3.1.6",
+    "@qilin-agent/sandbox-policy": "3.1.6",
+    "@qilin-agent/working-directory": "3.1.6",
+    "@qilin-agent/session-projection": "3.1.6"
   }
 }