@jangts/agent-core 0.1.0 → 0.2.0

package/development/skills/agent-core-app/scripts/plan.mjs

@@ -9,28 +9,53 @@ if (![1, 3].includes(args.length) || (args.length === 3 && args[1] !== '--source
   throw new Error('Usage: node plan.mjs PROJECT [--source UTF8_FILE]');
 const project = resolve(args[0]);
 let exists = true;
-try { if (!(await stat(project)).isDirectory()) throw new TypeError('PROJECT must be a directory'); }
-catch (error) { if (error.code !== 'ENOENT') throw error; exists = false; }
+try {
+  if (!(await stat(project)).isDirectory()) throw new TypeError('PROJECT must be a directory');
+} catch (error) {
+  if (error.code !== 'ENOENT') throw error;
+  exists = false;
+}
 const { sdk, tools, docs, knowledgeLoader } = await resolveSdkResources(project);
 let documents = [];
 let knowledgeConfigured = false;
 let knowledgeStatus = 'unconfigured';
 let baseConfigSha256;
 if (exists) {
-  try { await stat(resolve(project, 'knowledge.config.json')); knowledgeConfigured = true; }
-  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  try {
+    await stat(resolve(project, 'knowledge.config.json'));
+    knowledgeConfigured = true;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
   if (knowledgeConfigured) {
-    const { readApplicationKnowledge, compileApplicationKnowledge } = await import(pathToFileURL(knowledgeLoader));
+    const { readApplicationKnowledge, compileApplicationKnowledge } = await import(
+      pathToFileURL(knowledgeLoader)
+    );
     const snapshot = await readApplicationKnowledge(pathToFileURL(project + sep));
     const catalog = compileApplicationKnowledge(snapshot.documents, snapshot.policy);
-    documents = snapshot.policy.documents.map(item => ({ id: item.id, file: item.file }));
+    documents = snapshot.policy.documents.map((item) => ({ id: item.id, file: item.file }));
     knowledgeStatus = catalog.ids().length ? 'valid' : 'empty-awaiting-source';
     baseConfigSha256 = snapshot.baseConfigSha256;
   }
 }
-console.log(JSON.stringify({ project, mode: exists ? 'integrate-or-maintain' : 'create-application', sdk,
-  knowledgeConfigured, knowledgeStatus, baseConfigSha256, suppliedSource: args[2] ? resolve(args[2]) : null,
-  factsPolicy: 'Use only supplied source; with ideas only, keep knowledge files empty.',
-  documents, tools, docs,
-  changedFiles: [], published: false,
-}, null, 2));
+console.log(
+  JSON.stringify(
+    {
+      project,
+      mode: exists ? 'integrate-or-maintain' : 'create-application',
+      sdk,
+      knowledgeConfigured,
+      knowledgeStatus,
+      baseConfigSha256,
+      suppliedSource: args[2] ? resolve(args[2]) : null,
+      factsPolicy: 'Use only supplied source; with ideas only, keep knowledge files empty.',
+      documents,
+      tools,
+      docs,
+      changedFiles: [],
+      published: false,
+    },
+    null,
+    2,
+  ),
+);

package/development/skills/agent-core-app/scripts/prepare-source.mjs

@@ -1,3 +1,14 @@
+/*
+ * Prepare a knowledge candidate from a supplied source file.
+ *
+ * The script belongs to the App's development skills (开发技能). It never touches the
+ * active knowledge files: it validates the new document against the current catalog
+ * and writes a self-contained candidate directory that a later publication step can
+ * approve. The candidate records the base configuration hash and the revisions of the
+ * documents it was prepared against, so the publication can detect a stale base.
+ *
+ * Main exports: none. The file runs as a command and prints one JSON receipt.
+ */
 import { mkdir, writeFile } from 'node:fs/promises';
 import { resolve, join, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -8,17 +19,57 @@ import { readApplicationKnowledge, compileApplicationKnowledge } from './lib/kno
 const args = process.argv.slice(2);
 if (args.length !== 5 || args[1] !== '--source' || args[3] !== '--id')
   throw new Error('Usage: node prepare-source.mjs PROJECT --source UTF8_FILE --id DOCUMENT_ID');
-const project = resolve(args[0]), directory = pathToFileURL(project + sep);
+const project = resolve(args[0]),
+  // A trailing separator makes the directory a base URL, so relative entries
+  // resolve inside the project instead of against the file system root.
+  directory = pathToFileURL(project + sep);
 const { documents, policy, baseConfigSha256 } = await readApplicationKnowledge(directory);
-const previous = documents.find(item => item.id === args[4]);
-const source = await readSuppliedSource(resolve(args[2]), args[4], policy.maxDocumentBytes, previous?.locale);
-compileApplicationKnowledge([...documents.filter(item => item.id !== args[4]), source.document], policy);
-const target = join(project, '.local', 'knowledge-candidates', args[4].replace(/[^a-z0-9_.-]/g, '_') + '-' + randomUUID());
+// A document with the same id is replaced rather than added.
+const previous = documents.find((item) => item.id === args[4]);
+const source = await readSuppliedSource(
+  resolve(args[2]),
+  args[4],
+  policy.maxDocumentBytes,
+  // The locale of the replaced document is carried over, so the revision stays
+  // comparable across the replacement.
+  previous?.locale,
+);
+// The candidate must fit the catalog together with the other documents, so the
+// whole set is compiled before anything is written.
+compileApplicationKnowledge(
+  [...documents.filter((item) => item.id !== args[4]), source.document],
+  policy,
+);
+const target = join(
+  project,
+  '.local',
+  'knowledge-candidates',
+  // The random suffix keeps two candidates for the same document apart.
+  args[4].replace(/[^a-z0-9_.-]/g, '_') + '-' + randomUUID(),
+);
 await mkdir(target, { recursive: true });
+// `wx` fails instead of overwriting an existing file.
 await writeFile(join(target, 'source.knowledge.md'), source.bytes, { flag: 'wx' });
-await writeFile(join(target, 'proposal.json'), JSON.stringify({ schemaVersion: 1, status: 'candidate', document: args[4],
-  action: previous ? 'replace' : 'add', originalName: source.name, locale: source.document.locale,
-  contentSha256: source.digest, revision: source.document.revision, baseConfigSha256,
-  baseDocuments: documents.map(item => ({ id: item.id, revision: item.revision })), published: false,
-}, null, 2) + '\n', { flag: 'wx' });
+await writeFile(
+  join(target, 'proposal.json'),
+  JSON.stringify(
+    {
+      schemaVersion: 1,
+      status: 'candidate',
+      document: args[4],
+      action: previous ? 'replace' : 'add',
+      originalName: source.name,
+      locale: source.document.locale,
+      contentSha256: source.digest,
+      revision: source.document.revision,
+      baseConfigSha256,
+      baseDocuments: documents.map((item) => ({ id: item.id, revision: item.revision })),
+      published: false,
+    },
+    null,
+    2,
+  ) + '\n',
+  { flag: 'wx' },
+);
+// The receipt states that nothing was published and no active file was changed.
 console.log(JSON.stringify({ candidate: target, published: false, activeFilesChanged: false }));

package/development/skills/agent-core-app/scripts/resources.mjs

@@ -11,12 +11,17 @@ const assets = {
     'prepare-source': 'skills/agent-core-app/scripts/prepare-source.mjs',
   },
   docs: {
-    guide: 'docs/README.md', api: 'docs/api/README.md',
-    maintenance: 'docs/maintenance.md', flow: 'docs/flows/knowledge-maintenance.md',
-    gettingStarted: 'docs/getting-started.md', knowledge: 'docs/knowledge.md',
+    guide: 'docs/README.md',
+    api: 'docs/api/README.md',
+    maintenance: 'docs/maintenance.md',
+    flow: 'docs/flows/knowledge-maintenance.md',
+    gettingStarted: 'docs/getting-started.md',
+    knowledge: 'docs/knowledge.md',
     createApp: 'docs/create-app.md',
-    materials: 'docs/materials.md', memory: 'docs/memory-and-learning.md',
-    answering: 'docs/api/knowledge-answering.md', acceptance: 'docs/acceptance.md',
+    materials: 'docs/materials.md',
+    memory: 'docs/memory-and-learning.md',
+    answering: 'docs/api/knowledge-answering.md',
+    acceptance: 'docs/acceptance.md',
   },
 };
 
@@ -24,28 +29,37 @@ async function packageAt(directory) {
   try {
     const manifest = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8'));
     return manifest.name === packageName ? manifest : undefined;
-  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
 }
 
 async function installedPackage(project) {
   // Node resolves the public entry without loading it or evaluating App code.
   const require = createRequire(pathToFileURL(join(project, '__agent_core_resolution__.cjs')));
   let entry;
-  try { entry = require.resolve(packageName); }
-  catch (error) {
+  try {
+    entry = require.resolve(packageName);
+  } catch (error) {
     if (error.code !== 'MODULE_NOT_FOUND') throw error;
     // A broken installed entry must not silently select a different SDK version.
     for (const directory of require.resolve.paths(packageName) ?? []) {
-      try { await stat(join(directory, packageName)); }
-      catch (missing) { if (missing.code === 'ENOENT') continue; throw missing; }
+      try {
+        await stat(join(directory, packageName));
+      } catch (missing) {
+        if (missing.code === 'ENOENT') continue;
+        throw missing;
+      }
       throw error;
     }
     return;
   }
   for (let directory = dirname(entry); ; directory = dirname(directory)) {
     const manifest = await packageAt(directory);
-    if (manifest) return { root: directory, version: manifest.version, source: 'project-dependency' };
-    if (dirname(directory) === directory) throw new Error(`Cannot locate ${packageName} manifest for resolved entry ${entry}`);
+    if (manifest)
+      return { root: directory, version: manifest.version, source: 'project-dependency' };
+    if (dirname(directory) === directory)
+      throw new Error(`Cannot locate ${packageName} manifest for resolved entry ${entry}`);
   }
 }
 
@@ -60,16 +74,30 @@ export async function resolveSdkResources(project) {
   if (!sdk) {
     // Only the Skill distributed inside the SDK can use sibling assets.
     const root = fileURLToPath(new URL('../../../../', import.meta.url));
-    const bundled = resolve(fileURLToPath(import.meta.url)) === resolve(root, 'development/skills/agent-core-app/scripts/resources.mjs');
+    const bundled =
+      resolve(fileURLToPath(import.meta.url)) ===
+      resolve(root, 'development/skills/agent-core-app/scripts/resources.mjs');
     const manifest = bundled ? await packageAt(root) : undefined;
-    if (!manifest) throw new Error(`Cannot resolve ${packageName} from ${project}. Install the SDK and its real dependencies in the existing App, or use the Skill inside the distributed SDK.`);
+    if (!manifest)
+      throw new Error(
+        `Cannot resolve ${packageName} from ${project}. Install the SDK and its real dependencies in the existing App, or use the Skill inside the distributed SDK.`,
+      );
     sdk = { root, version: manifest.version, source: 'bundled-sdk' };
   }
   const resources = {};
   for (const [group, entries] of Object.entries(assets)) {
-    resources[group] = Object.fromEntries(await Promise.all(Object.entries(entries)
-      .map(async ([name, relative]) => [name, await requiredFile(sdk.root, relative)])));
+    resources[group] = Object.fromEntries(
+      await Promise.all(
+        Object.entries(entries).map(async ([name, relative]) => [
+          name,
+          await requiredFile(sdk.root, relative),
+        ]),
+      ),
+    );
   }
-  const knowledgeLoader = await requiredFile(sdk.root, 'skills/agent-core-app/scripts/lib/knowledge.mjs');
+  const knowledgeLoader = await requiredFile(
+    sdk.root,
+    'skills/agent-core-app/scripts/lib/knowledge.mjs',
+  );
   return { sdk, ...resources, knowledgeLoader };
 }

package/development/skills/agent-core-app/scripts/validate-knowledge.mjs

@@ -1,8 +1,25 @@
+/*
+ * Validate the active knowledge catalog of one project.
+ *
+ * The script belongs to the App's development skills (开发技能). It loads the App-owned
+ * configuration and document files, compiles them into a Knowledge catalog and reports
+ * the resulting document ids. An empty catalog is reported as a distinct status, so a
+ * project that has not received its first source is not confused with a broken one.
+ *
+ * Main exports: none. The file runs as a command and prints one JSON receipt.
+ */
 import { pathToFileURL } from 'node:url';
 import { resolve, sep } from 'node:path';
 import { loadApplicationKnowledge } from './lib/knowledge.mjs';
 
 if (process.argv.length !== 3) throw new Error('Usage: node validate-knowledge.mjs PROJECT');
+// A trailing separator turns the project path into a base URL, so the document
+// entries resolve inside the project directory.
 const directory = pathToFileURL(resolve(process.argv[2]) + sep);
 const catalog = await loadApplicationKnowledge(directory);
-console.log(JSON.stringify({ status: catalog.ids().length ? 'valid' : 'empty-awaiting-source', documents: catalog.ids() }));
+console.log(
+  JSON.stringify({
+    status: catalog.ids().length ? 'valid' : 'empty-awaiting-source',
+    documents: catalog.ids(),
+  }),
+);

package/development/skills/agent-core-app/templates/catalog.json

@@ -1,25 +1,39 @@
 {
   "schemaVersion": 1,
-  "templates": [{
-    "id": "node-ts",
-    "revision": "1",
-    "directory": "node-ts",
-    "files": [
-      { "origin": "template", "source": "package.json.tpl", "target": "package.json" },
-      { "origin": "template", "source": "tsconfig.json.tpl", "target": "tsconfig.json" },
-      { "origin": "template", "source": "gitignore.tpl", "target": ".gitignore" },
-      { "origin": "template", "source": "env.example.tpl", "target": ".env.example" },
-      { "origin": "template", "source": "README.md.tpl", "target": "README.md" },
-      { "origin": "template", "source": "src/config.ts.tpl", "target": "src/config.ts" },
-      { "origin": "template", "source": "src/app.ts.tpl", "target": "src/app.ts" },
-      { "origin": "template", "source": "src/catalog.ts.tpl", "target": "src/catalog.ts" },
-      { "origin": "template", "source": "src/handlers.ts.tpl", "target": "src/handlers.ts" },
-      { "origin": "template", "source": "src/model.ts.tpl", "target": "src/model.ts" },
-      { "origin": "template", "source": "scripts/knowledge.mjs.tpl", "target": "scripts/knowledge.mjs" },
-      { "origin": "skill", "source": "scripts/resources.mjs", "target": "scripts/sdk-resources.mjs" },
-      { "origin": "template", "source": "examples/ask.mjs.tpl", "target": "examples/ask.mjs" },
-      { "origin": "template", "source": "test/app.test.mjs.tpl", "target": "test/app.test.mjs" },
-      { "origin": "template", "source": "knowledge/knowledge.config.json.tpl", "target": "knowledge/knowledge.config.json" }
-    ]
-  }]
+  "templates": [
+    {
+      "id": "node-ts",
+      "revision": "1",
+      "directory": "node-ts",
+      "files": [
+        { "origin": "template", "source": "package.json.tpl", "target": "package.json" },
+        { "origin": "template", "source": "tsconfig.json.tpl", "target": "tsconfig.json" },
+        { "origin": "template", "source": "gitignore.tpl", "target": ".gitignore" },
+        { "origin": "template", "source": "env.example.tpl", "target": ".env.example" },
+        { "origin": "template", "source": "README.md.tpl", "target": "README.md" },
+        { "origin": "template", "source": "src/config.ts.tpl", "target": "src/config.ts" },
+        { "origin": "template", "source": "src/app.ts.tpl", "target": "src/app.ts" },
+        { "origin": "template", "source": "src/catalog.ts.tpl", "target": "src/catalog.ts" },
+        { "origin": "template", "source": "src/handlers.ts.tpl", "target": "src/handlers.ts" },
+        { "origin": "template", "source": "src/model.ts.tpl", "target": "src/model.ts" },
+        {
+          "origin": "template",
+          "source": "scripts/knowledge.mjs.tpl",
+          "target": "scripts/knowledge.mjs"
+        },
+        {
+          "origin": "skill",
+          "source": "scripts/resources.mjs",
+          "target": "scripts/sdk-resources.mjs"
+        },
+        { "origin": "template", "source": "examples/ask.mjs.tpl", "target": "examples/ask.mjs" },
+        { "origin": "template", "source": "test/app.test.mjs.tpl", "target": "test/app.test.mjs" },
+        {
+          "origin": "template",
+          "source": "knowledge/knowledge.config.json.tpl",
+          "target": "knowledge/knowledge.config.json"
+        }
+      ]
+    }
+  ]
 }

package/dist/cjs/capabilities/index.js

@@ -15,6 +15,19 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.commandSchema = exports.defineCommand = void 0;
+/**
+ * Capability registration surface: model capabilities, executable tools and host-selected
+ * invocations.
+ *
+ * These registries hold declarations only. Which capabilities a stage may use, whether a
+ * call is authorized, and what a payload means remain App decisions; this barrel provides
+ * the mechanisms that validate, seal and execute those declarations.
+ *
+ * Exports: the model capability registry (`model`), the executable tool registry and its
+ * sync/async invocation entry points (`tools`), host-selected invocation execution
+ * (`invocation`), and the Interaction Kit's protocol, command and handler definitions that
+ * shape and validate model-produced interactions.
+ */
 __exportStar(require("./model.js"), exports);
 __exportStar(require("./tools.js"), exports);
 __exportStar(require("./invocation.js"), exports);

package/dist/cjs/capabilities/invocation.js

@@ -1,31 +1,84 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeInvocation = executeInvocation;
+/**
+ * Execution of one host-selected synchronous invocation.
+ *
+ * An invocation is the smallest Core-owned unit of work: the App decides which handler to
+ * call and supplies payload and authorization facts, while this module runs the handler once,
+ * threads cancellation and diagnostics, and pairs an optional journal start with a receipt.
+ * Selection, authorization and retries stay outside.
+ *
+ * Exports: `executeInvocation` and the invocation contracts re-exported at the bottom.
+ */
 const invocation_js_1 = require("../utils/invocation.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 const index_js_1 = require("../diagnostics/index.js");
 const reporting_js_1 = require("../execution/reporting.js");
-/** Execute a host-selected synchronous call. Selection, authorization facts and payload shape stay outside. */
+/**
+ * Run one synchronous invocation and record its effects.
+ *
+ * @param invocation Handler whose `call` performs the work; its `id` becomes the tool id in
+ *   diagnostics and journal records.
+ * @param input Payload handed to the handler unchanged.
+ * @param context App context passed to the ports below; it is never inspected here.
+ * @param ports Per-context callbacks for diagnostics, cancellation, journalling and receipt
+ *   capture. All are optional: without them the handler still runs, just unrecorded.
+ * @returns Nothing. The outcome is conveyed through the journal receipt, when one is bound.
+ * @throws TypeError when the handler identity is missing, or when the handler returns a
+ *   promise despite the synchronous contract.
+ * @throws Whatever the handler throws, unchanged, including the abort error raised by the
+ *   signal checks.
+ */
 function executeInvocation(invocation, input, context, ports = {}) {
     const toolId = invocation.id;
+    // Identify the call before touching the ports: journal and diagnostics records cannot be
+    // reconciled with an anonymous handler.
     if (!toolId?.trim())
         throw new TypeError('Invalid invocation handler identity');
     const journal = ports.journal?.(context), id = (0, invocation_js_1.invocationId)(), startedAtMs = Date.now();
-    const diagnostics = ports.diagnostics?.(context)?.child(id, { invocationId: id, nodeRole: 'invocation', definitionKind: 'tool-invocation', definitionId: toolId, nodeId: toolId, nodeName: toolId, nodeKind: 'tool-invocation' });
-    const callId = journal?.beginTool({ toolId, input, invocation: { ...diagnostics?.identity, invocationId: id, startedAtMs } });
-    diagnostics?.emit('tool.call', () => ({ toolId, invocationId: id, ...(diagnostics?.enabled('tool.call', 'content') ? { input } : {}) }));
+    const diagnostics = ports.diagnostics?.(context)?.child(id, {
+        invocationId: id,
+        nodeRole: 'invocation',
+        definitionKind: 'tool-invocation',
+        definitionId: toolId,
+        nodeId: toolId,
+        nodeName: toolId,
+        nodeKind: 'tool-invocation',
+    });
+    const callId = journal?.beginTool({
+        toolId,
+        input,
+        invocation: { ...diagnostics?.identity, invocationId: id, startedAtMs },
+    });
+    diagnostics?.emit('tool.call', () => ({
+        toolId,
+        invocationId: id,
+        ...(diagnostics?.enabled('tool.call', 'content') ? { input } : {}),
+    }));
+    // Held outside the try block so the failure path can still tell cancellation from an error.
     let activeSignal;
     let reports;
     try {
         const checkpoint = ports.checkpoint?.(context);
-        const signal = activeSignal = ports.signal?.(context);
+        const signal = (activeSignal = ports.signal?.(context));
         signal?.throwIfAborted();
         reports = new reporting_js_1.NodeReports(diagnostics, signal, 'tool.result');
-        (0, synchronous_js_1.synchronous)(invocation.call(input, context, { mode: 'sync', invocationId: id, signal: signal ?? new AbortController().signal, diagnostics,
-            report: reports.report.bind(reports), createSubFlowLogger: reports.createSubFlowLogger.bind(reports) }), 'Invocation handlers must be synchronous');
+        // The helper rejects a promise and drains its rejection: a handler that turns async must
+        // fail here instead of escaping as an unhandled rejection.
+        (0, synchronous_js_1.synchronous)(invocation.call(input, context, {
+            mode: 'sync',
+            invocationId: id,
+            signal: signal ?? new AbortController().signal,
+            diagnostics,
+            report: reports.report.bind(reports),
+            createSubFlowLogger: reports.createSubFlowLogger.bind(reports),
+        }), 'Invocation handlers must be synchronous');
         ports.signal?.(context)?.throwIfAborted();
         if (callId) {
             const receipt = ports.receipt?.(context, checkpoint);
+            // Cancellation may have arrived while the handler or receipt ran; a successful record
+            // must not be committed for a request the host has already abandoned.
             ports.signal?.(context)?.throwIfAborted();
             journal.finishTool({ invocationId: callId, status: 'success', value: receipt });
         }
@@ -34,15 +87,32 @@ function executeInvocation(invocation, input, context, ports = {}) {
     }
     catch (error) {
         reports?.close();
-        diagnostics?.emit('tool.result', () => ({ toolId, invocationId: id, status: activeSignal?.aborted ? 'cancelled' : 'error', durationMs: Date.now() - startedAtMs, ...(diagnostics?.enabled('tool.result', 'content') ? { error: (0, index_js_1.diagnosticError)(error) } : {}) }), reports?.debug());
+        diagnostics?.emit('tool.result', () => ({
+            toolId,
+            invocationId: id,
+            status: activeSignal?.aborted ? 'cancelled' : 'error',
+            durationMs: Date.now() - startedAtMs,
+            ...(diagnostics?.enabled('tool.result', 'content')
+                ? { error: (0, index_js_1.diagnosticError)(error) }
+                : {}),
+        }), reports?.debug());
         try {
             if (callId)
-                journal.finishTool({ invocationId: callId, status: ports.signal?.(context)?.aborted ? 'cancelled' : 'error', value: ports.receiptError?.(error) });
+                journal.finishTool({
+                    invocationId: callId,
+                    // The signal, not the error shape, decides whether this counts as cancellation.
+                    status: ports.signal?.(context)?.aborted ? 'cancelled' : 'error',
+                    value: ports.receiptError?.(error),
+                });
+        }
+        catch {
+            /* Preserve the invocation failure if receipt recording also fails. */
         }
-        catch { /* Preserve the invocation failure if receipt recording also fails. */ }
         throw error;
     }
     finally {
+        // Closing is idempotent, so a port that throws on the success path still releases the
+        // reporting scope.
         reports?.close();
     }
 }