@jangts/agent-core 0.1.1 → 0.2.1

package/development/docs/operations.en.md

@@ -0,0 +1,51 @@
+# Result delivery, diagnostics, and operations
+
+[Back to development handbook](README.md) · [Core API](api/core.md) · [Support API](api/support.md)
+
+## Boundary of each run
+
+Keep startup manifests separate from per-request state. For each request, establish identity, the allowed knowledge view, an `AbortSignal`, model/tool budget, and source and output state. Credentials, endpoints, model characteristics, and error mapping for connecting to the Provider are managed by the App server, and user materials or model parameters are not allowed to override these configurations.
+
+Consider rounds, model call counts, timeouts, message and output characters, schema size, and business tool quotas separately. Repair, review, and fallback also consume budget; a step called "recovery" cannot mean unlimited retries. Core's model call budget covers only calls that actually pass through that runner; external HTTP, background jobs, and model calls made by the App itself must be limited by the App.
+
+Cancellation must reach the actual model and business I/O; for writes already started, cancellation does not mean rollback. The App should be able to judge whether an operation has executed by idempotency key/real receipt, and query state before retrying. Synchronous ToolRegistry does not wait for arbitrary Promises; asynchronous business logic should be placed in suitable asynchronous handlers/nodes and must not fake synchronous success.
+
+## Verify facts first, then form presentable output
+
+```text
+Parsed model proposal
+  → authorization and real execution
+  → input/output contracts and source checks
+  → generate candidate reply
+  → completeness/business fact checks
+  → program binds sources, action states, and links
+  → deliver in the form chosen by the App
+```
+
+A Knowledge Snapshot is a source reference, a tool event is an execution record, and model text is a candidate explanation; the three do not substitute for each other. Answering's tasks, checks, and bounded repair help organize this chain; the concrete fact checks are provided by the App. See the [knowledge answering API](api/knowledge-answering.md) for the relevant local contracts.
+
+Presentation/Interaction is an optional Kit. InteractionProtocol/CommandCatalog does not determine how the App exchanges data between front end and back end; when used, the App registers commands, parsing, and presentation implementations, and still needs actual receipts from the peer. The App may also directly adopt its own HTTP/SSE/event protocol.
+
+## Error exits
+
+| Actual cause | Program handling | Direction of user-facing wording |
+| --- | --- | --- |
+| Source not provided or not allowed to read | Do not widen permissions, do not generate fake facts | State which kind of available knowledge is missing |
+| Parameters or output violate the contract | Record the specific stage and code; repair or end within budget | State the actual action not completed this time |
+| Provider stream break/timeout | Save known execution state, retry with bounds | Reply incomplete, can retry |
+| Insufficient budget/read limit exceeded | Narrow the legal scope or split the task | State the scope limit; no silent truncation |
+| User cancellation | Stop cancellable work, verify executed operations | State clearly that it stopped and what is confirmed |
+
+Error messages should not show internal schemas, tokens, call protocols, or stack traces verbatim. Logs keep machine-locatable fields, and user copy keeps the accurate cause; not every failure should be described as a connectivity problem.
+
+## What observation and persistence each own
+
+Core's run records/diagnostics and Support's Provider observer provide observation boundaries; they do not automatically create a log database. The App decides whether to output to the console, files, telemetry systems, or a persistent repository, and how to authorize queries, redaction, and retention. `breakWhile` tags are classification hints for interruption, not permission or rule filtering switches; follow the [Support reference](api/support.md).
+
+It is recommended to correlate request/run, stage, model or tool call ID, business error code, knowledge revision/snapshot id, and actual duration. By default do not collect credentials, full prompts, user materials, or model body text; when body-text diagnostics are needed, the product must explicitly enable and limit the scope. Observation callbacks should not change business returns or escalate a record failure into duplicate execution.
+
+## Publication and recovery
+
+Deliver code manifests, knowledge, task references, and configuration as one verifiable version. Validate references before publication and prepare a rollback version; new requests switch to the new catalog while existing requests hold old snapshots. Whether multi-file or database publication is atomic is implemented by the App; the Knowledge in-memory catalog itself provides no storage transactions.
+
+When the App publishes, also state the enabled capabilities, knowledge version, configuration, and changes in externally visible behavior; the new version must still preserve the original permissions, budget, cancellation, and delivery guarantees.

package/development/docs/records.en.md

@@ -0,0 +1,63 @@
+# App data format examples
+
+The JSON below only explains field design for App-owned records; it does not participate in runtime loading, register capabilities, or create data tables. Core does not require this storage format.
+
+Use null/empty arrays to indicate not yet provided, and do not fabricate facts from example default values. Field names, states, and versions are defined and validated by the App itself.
+
+## Material record
+
+Original, extraction status, ownership, lifecycle, and publication status.
+
+```json
+{
+  "schemaVersion": 1,
+  "id": null,
+  "ownerId": null,
+  "scope": "private",
+  "original": { "reference": null, "mediaType": null, "contentSha256": null, "receivedAt": null },
+  "extraction": { "status": "pending", "revision": null, "text": null, "caveats": [] },
+  "lifetime": "turn",
+  "expiresAt": null,
+  "publication": { "status": "unpublished", "documentId": null }
+}
+```
+
+## User preferences
+
+Accumulated interaction preferences, source watermark, and version.
+
+```json
+{
+  "schemaVersion": 1,
+  "ownerId": null,
+  "revision": null,
+  "summary": null,
+  "sourceWindow": { "after": null, "through": null, "references": [] },
+  "updatedAt": null,
+  "expiresAt": null,
+  "status": "uninitialized"
+}
+```
+
+## Experience candidate
+
+Experience source, applicability, validation, and publication status.
+
+```json
+{
+  "schemaVersion": 1,
+  "id": null,
+  "ownerId": null,
+  "revision": null,
+  "status": "candidate",
+  "claim": null,
+  "applicability": [],
+  "sources": [],
+  "counterexamples": [],
+  "conflicts": [],
+  "validation": { "status": "pending", "references": [] },
+  "publication": { "approvedBy": null, "approvedAt": null, "documentId": null }
+}
+```
+
+User preferences cannot carry identity and permissions; experience candidates are not published automatically; raw materials do not automatically enter shared knowledge. See [Knowledge maintenance](maintenance.md), [Materials](materials.md), and [Continuous accumulation](memory-and-learning.md).

package/development/docs/registration.en.md

@@ -0,0 +1,63 @@
+# Registration, assembly, and execution
+
+[Back to development handbook](README.md)
+
+## Ordinary tool integration
+
+Prefer putting static tool definitions in a separate, readable, typed manifest, preserving item types with Support.defineTool, and assembling with Support.defineToolCatalog. Each item contains id, kind, description, inputSchema, authorize, execute, and parseOutput; inputSchema provides both jsonSchema and parse; model capabilities and execution registration consume the same definition. For complete code see [Tool integration](basic-usage.md#tools-are-declared-only-once).
+
+Create catalog.bind({ app: context, execution: { signal } }) per request; the model first produces a ToolProposal, and the App then calls runtime.invoke. The latter reuses Core ToolRegistry.invokeAsync, performing input parsing, actual authorization, execution, and output checks in order. When the available set changes, use catalog.select(ids) to project the same manifest, and still check the real identity at execution. This Support adapter does not replace workflows or the business specifications of Kits.
+
+## Two different kinds of registration
+
+| Registered object | Purpose | Update method |
+| --- | --- | --- |
+| Tools/model capabilities/workflows/checks/output | Declare what the program can do, when it is available, what it accepts, and who implements it | The App compiles manifests and provides the available set by stage and real identity |
+| Documents/sections/knowledge versions | Declare what content a given read can see | The App loads sources and creates a Knowledge catalog; on update, explicitly rebuild the catalog and related views |
+
+Adding one knowledge document usually does not require adding a tool. Keep a single `knowledge.read`, and let the catalog authorized for this round provide legal document/section IDs. The model may propose read requests from the provided set, but cannot use them to register arbitrary new handlers, discover disk directories, or publish knowledge.
+
+## What a manifest should state
+
+At minimum it should be possible to read: stable identifier, purpose, input and output, real execution entry, availability conditions, read scope, side effects, errors, and receipts. Derive the model-visible catalog, schema, and reference validation from the manifest wherever possible; do not maintain one prompt capability list and another actual execution list.
+
+- `ModelCapabilityRegistry` registers the structures the model can propose along with `inputSchema` and `resolve`. inputSchema.jsonSchema is used for model declarations; business parsing, value ranges, and authorization must still be enforced by the program.
+- `ToolRegistry` registers `id/kind/parseInput/execute/parseOutput`. invoke is for synchronous implementations; invokeAsync waits for asynchronous execution before checking output and recording results; do not hand a Promise to the synchronous entry as a completed result.
+- `AgentCoreEngine` workflow nodes declare `requires/provides/routes/onErrorNodeId`. Only updates that pass cancellation and state contract checks are committed; branches are selected in declaration order.
+- `Support.defineContextFragments` assembles request input and fragments. Trust, source, and budget must be correctly labeled by the App; client self-reporting alone is not acceptable.
+- Knowledge, Answering, Presentation, Interaction, Intents, and Tools each own local contracts and are chosen according to business needs. They are not automatically installed by Core.
+
+For named constructors, static helpers, and instance methods see [Core](api/core.md), [Support](api/support.md), and [Kit](api/kits.md).
+
+## Separate model proposals from actual execution
+
+```text
+Server establishes identity and the available capability view
+  → model proposes capability + parameters
+  → Core collects the complete response, validates with inputSchema.parse, then calls the registered resolve
+  → App selects the actual execution entry
+  → tool parameter parsing → authorization by server-side identity → execute → output checks
+  → program records actual sources/execution receipts
+  → generation, checks, binding, and delivery
+```
+
+`parse` should not incidentally perform writes, send messages, or call business tools. Nor should a success receipt be generated merely because the model says it is "done". Using the Interaction Kit for cross-end actions merely selects an optional exchange specification; the App still needs to implement peer handlers, identity, permissions, and confirmation of actual results.
+
+## Static manifests and in-request views
+
+Known tools and local protocols are suitable for registration at startup. Authorization, page environment, current tenant, and allowed knowledge change per request and should be projected into the visible set during this round's assembly. Model visibility limits do not replace execution-time authorization.
+
+When new documents must be available immediately: load new knowledge → validate catalog and task references → build a new version catalog → atomically switch the App's current reference. Existing requests keep their old catalog and snapshots; new requests use the new catalog. Do not mix body text, schema, sources, and revisions from before and after the reload within the same answer.
+
+When program capabilities must genuinely be added dynamically, the App explicitly decides the code source, publication, and registration point, and reconstructs the corresponding registry. The library has no model-driven arbitrary code installation, automatic file discovery, or hot-unloading platform.
+
+## Checks at startup and per request
+
+| Timing | What to check |
+| --- | --- |
+| Startup/publication | Whether handlers exist; whether node and output references are valid; whether knowledge/sections exist; whether the Skill's tools are actually registered; whether parameter schema and parser agree |
+| Request start | Identity, knowledge access scope, budget, signal, current catalog revision, and capability set |
+| Before real execution | Current permissions, resource ownership, parameter value ranges, and necessary confirmation |
+| Before delivery | Tool result contracts, sources and numbers, generated fields, program-bound fields, output completeness |
+
+A Kit's validator can only validate the local structure it knows about. It does not know your tenants, storage paths, data permissions, or business facts; these checks cannot be omitted just because "a creator was used".

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

@@ -1,149 +1,365 @@
+/**
+ * Scaffold or compare an App that uses `@jangts/agent-core`.
+ *
+ * Resolves the SDK the target project depends on, renders the selected template into a staging
+ * directory and only then renames it into place, so a failed or concurrent run never leaves a
+ * half-written app. `--check` compares the managed files against the recorded receipt instead of
+ * writing. Nothing here installs dependencies, calls a model or publishes content.
+ *
+ * Usage: see `usage` below; run directly or import `createApplication`.
+ */
 import { createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import {
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  rmdir,
+  writeFile,
+} from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { resolveSdkResources } from './resources.mjs';
 
-const execute = promisify(execFile), receiptName = 'agent-core.template.json';
-const usage = 'node create-app.mjs TARGET [--name PACKAGE_NAME] [--purpose TEXT] [--template node-ts] [--sdk-from PROJECT] [--source UTF8_FILE --id DOCUMENT_ID] [--write | --check]';
-const hash = value => createHash('sha256').update(value).digest('hex');
-const pathInside = value => typeof value === 'string' && !!value && !isAbsolute(value) && !value.includes('\\')
-  && value.split('/').every(part => !!part && !['.', '..'].includes(part));
-async function exists(path) { try { return await lstat(path); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
+const execute = promisify(execFile),
+  receiptName = 'agent-core.template.json';
+const usage =
+  'node create-app.mjs TARGET [--name PACKAGE_NAME] [--purpose TEXT] [--template node-ts] [--sdk-from PROJECT] [--source UTF8_FILE --id DOCUMENT_ID] [--write | --check]';
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const pathInside = (value) =>
+  typeof value === 'string' &&
+  !!value &&
+  !isAbsolute(value) &&
+  !value.includes('\\') &&
+  value.split('/').every((part) => !!part && !['.', '..'].includes(part));
+async function exists(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}
 function inputs(name, purpose) {
-  if (typeof name !== 'string' || name.length > 214 || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(name)) throw new TypeError('Use a lowercase npm package name');
-  if (typeof purpose !== 'string' || purpose.length > 800 || !purpose.trim()) throw new TypeError('Use a purpose of 1–800 characters');
+  if (
+    typeof name !== 'string' ||
+    name.length > 214 ||
+    !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(name)
+  )
+    throw new TypeError('Use a lowercase npm package name');
+  if (typeof purpose !== 'string' || purpose.length > 800 || !purpose.trim())
+    throw new TypeError('Use a purpose of 1–800 characters');
   return { name, purpose: purpose.trim() };
 }
 function parse(args, cwd) {
   if (!args.length || args[0].startsWith('--')) throw new TypeError(usage);
-  const values = {}, switches = new Set(['--write', '--check']), options = new Set(['--name', '--purpose', '--template', '--sdk-from', '--source', '--id']);
+  const values = {},
+    switches = new Set(['--write', '--check']),
+    options = new Set(['--name', '--purpose', '--template', '--sdk-from', '--source', '--id']);
   for (let index = 1; index < args.length; index++) {
     const key = args[index];
     if (Object.hasOwn(values, key)) throw new TypeError(`Duplicate option: ${key}`);
     if (switches.has(key)) values[key] = true;
-    else if (options.has(key) && args[index + 1] !== undefined && !args[index + 1].startsWith('--')) values[key] = args[++index];
+    else if (options.has(key) && args[index + 1] !== undefined && !args[index + 1].startsWith('--'))
+      values[key] = args[++index];
     else throw new TypeError(usage);
   }
-  if (values['--write'] && values['--check'] || !!values['--source'] !== !!values['--id']
-    || values['--check'] && ['--name', '--purpose', '--source', '--id'].some(key => Object.hasOwn(values, key))) throw new TypeError(usage);
+  if (
+    (values['--write'] && values['--check']) ||
+    !!values['--source'] !== !!values['--id'] ||
+    (values['--check'] &&
+      ['--name', '--purpose', '--source', '--id'].some((key) => Object.hasOwn(values, key)))
+  )
+    throw new TypeError(usage);
   return { target: resolve(cwd, args[0]), values };
 }
 async function emptyTarget(target) {
   const item = await exists(target);
-  if (item && (!item.isDirectory() || item.isSymbolicLink() || (await readdir(target)).length)) throw new Error('TARGET must be absent or an empty real directory; existing files are preserved');
+  if (item && (!item.isDirectory() || item.isSymbolicLink() || (await readdir(target)).length))
+    throw new Error(
+      'TARGET must be absent or an empty real directory; existing files are preserved',
+    );
 }
 async function templateResources(resources, id) {
   const root = join(resources.sdk.root, 'development/skills/agent-core-app');
   const catalog = JSON.parse(await readFile(join(root, 'templates/catalog.json'), 'utf8'));
-  if (catalog.schemaVersion !== 1 || !Array.isArray(catalog.templates)) throw new Error('Unsupported template catalog');
-  const template = catalog.templates.find(item => item.id === id);
-  if (!template || typeof template.revision !== 'string' || !pathInside(template.directory) || !Array.isArray(template.files)
-    || template.files.some(file => !pathInside(file.source) || !pathInside(file.target) || !['template', 'skill'].includes(file.origin))
-    || new Set(template.files.map(file => file.target)).size !== template.files.length || template.files.some(file => file.target === receiptName)) throw new Error('Invalid or unknown template');
+  if (catalog.schemaVersion !== 1 || !Array.isArray(catalog.templates))
+    throw new Error('Unsupported template catalog');
+  const template = catalog.templates.find((item) => item.id === id);
+  if (
+    !template ||
+    typeof template.revision !== 'string' ||
+    !pathInside(template.directory) ||
+    !Array.isArray(template.files) ||
+    template.files.some(
+      (file) =>
+        !pathInside(file.source) ||
+        !pathInside(file.target) ||
+        !['template', 'skill'].includes(file.origin),
+    ) ||
+    new Set(template.files.map((file) => file.target)).size !== template.files.length ||
+    template.files.some((file) => file.target === receiptName)
+  )
+    throw new Error('Invalid or unknown template');
   return { root, template };
 }
 async function render(resources, definition, input) {
   const manifest = JSON.parse(await readFile(join(resources.sdk.root, 'package.json'), 'utf8'));
-  if (manifest.name !== '@jangts/agent-core' || manifest.version !== resources.sdk.version || typeof manifest.devDependencies?.typescript !== 'string') throw new Error('SDK manifest does not describe the selected template dependencies');
-  const configuration = { name: input.name, purpose: input.purpose, maxCalls: 4, maxRounds: 8,
-    callTimeoutMs: 30000, maxInputChars: 48000, maxOutputChars: 8000 };
-  const substitutions = { '__APP_CONFIG__': JSON.stringify(configuration, null, 2), '__PACKAGE_NAME__': JSON.stringify(input.name),
-    '__SDK_VERSION__': JSON.stringify(manifest.version), '__TYPESCRIPT_VERSION__': JSON.stringify(manifest.devDependencies.typescript) };
-  return Promise.all(definition.template.files.map(async file => {
-    const source = file.origin === 'skill' ? join(definition.root, file.source) : join(definition.root, 'templates', definition.template.directory, file.source);
-    const info = await lstat(source); if (!info.isFile() || info.isSymbolicLink()) throw new Error('Template assets must be regular files');
-    let content = new TextDecoder('utf-8', { fatal: true }).decode(await readFile(source));
-    // One pass: user-provided purpose text cannot become another substitution instruction.
-    if (file.origin === 'template') content = content.replace(/__APP_CONFIG__|__PACKAGE_NAME__|__SDK_VERSION__|__TYPESCRIPT_VERSION__/g, token => substitutions[token]);
-    const bytes = Buffer.from(content); return { path: file.target, bytes, sha256: hash(bytes) };
-  }));
+  if (
+    manifest.name !== '@jangts/agent-core' ||
+    manifest.version !== resources.sdk.version ||
+    typeof manifest.devDependencies?.typescript !== 'string'
+  )
+    throw new Error('SDK manifest does not describe the selected template dependencies');
+  const configuration = {
+    name: input.name,
+    purpose: input.purpose,
+    maxCalls: 4,
+    maxRounds: 8,
+    callTimeoutMs: 30000,
+    maxInputChars: 48000,
+    maxOutputChars: 8000,
+  };
+  const substitutions = {
+    __APP_CONFIG__: JSON.stringify(configuration, null, 2),
+    __PACKAGE_NAME__: JSON.stringify(input.name),
+    __SDK_VERSION__: JSON.stringify(manifest.version),
+    __TYPESCRIPT_VERSION__: JSON.stringify(manifest.devDependencies.typescript),
+  };
+  return Promise.all(
+    definition.template.files.map(async (file) => {
+      const source =
+        file.origin === 'skill'
+          ? join(definition.root, file.source)
+          : join(definition.root, 'templates', definition.template.directory, file.source);
+      const info = await lstat(source);
+      if (!info.isFile() || info.isSymbolicLink())
+        throw new Error('Template assets must be regular files');
+      let content = new TextDecoder('utf-8', { fatal: true }).decode(await readFile(source));
+      // One pass: user-provided purpose text cannot become another substitution instruction.
+      if (file.origin === 'template')
+        content = content.replace(
+          /__APP_CONFIG__|__PACKAGE_NAME__|__SDK_VERSION__|__TYPESCRIPT_VERSION__/g,
+          (token) => substitutions[token],
+        );
+      const bytes = Buffer.from(content);
+      return { path: file.target, bytes, sha256: hash(bytes) };
+    }),
+  );
 }
 async function compare(target, resources, definition) {
   const directory = await lstat(target);
-  if (!directory.isDirectory() || directory.isSymbolicLink()) throw new Error('TARGET must be a real directory');
-  const receiptPath = join(target, receiptName), info = await lstat(receiptPath);
-  if (!info.isFile() || info.isSymbolicLink()) throw new Error('Template receipt must be a regular file');
+  if (!directory.isDirectory() || directory.isSymbolicLink())
+    throw new Error('TARGET must be a real directory');
+  const receiptPath = join(target, receiptName),
+    info = await lstat(receiptPath);
+  if (!info.isFile() || info.isSymbolicLink())
+    throw new Error('Template receipt must be a regular file');
   const receipt = JSON.parse(await readFile(receiptPath, 'utf8'));
-  if (receipt.schemaVersion !== 1 || receipt.template?.id !== definition.template.id || !Array.isArray(receipt.files)
-    || receipt.files.some(file => !pathInside(file.path) || !/^[a-f0-9]{64}$/.test(file.sha256))
-    || new Set(receipt.files.map(file => file.path)).size !== receipt.files.length) throw new Error('Invalid template receipt');
-  const files = await render(resources, definition, inputs(receipt.inputs?.name, receipt.inputs?.purpose));
-  const baseline = new Map(receipt.files.map(file => [file.path, file.sha256])), currentTemplate = new Map(files.map(file => [file.path, file.sha256]));
+  if (
+    receipt.schemaVersion !== 1 ||
+    receipt.template?.id !== definition.template.id ||
+    !Array.isArray(receipt.files) ||
+    receipt.files.some((file) => !pathInside(file.path) || !/^[a-f0-9]{64}$/.test(file.sha256)) ||
+    new Set(receipt.files.map((file) => file.path)).size !== receipt.files.length
+  )
+    throw new Error('Invalid template receipt');
+  const files = await render(
+    resources,
+    definition,
+    inputs(receipt.inputs?.name, receipt.inputs?.purpose),
+  );
+  const baseline = new Map(receipt.files.map((file) => [file.path, file.sha256])),
+    currentTemplate = new Map(files.map((file) => [file.path, file.sha256]));
   const changes = [];
   for (const path of [...new Set([...baseline.keys(), ...currentTemplate.keys()])].sort()) {
-    if (!currentTemplate.has(path)) { changes.push({ path, state: 'not-in-current-template', baselineSha256: baseline.get(path), templateChanged: true }); continue; }
+    if (!currentTemplate.has(path)) {
+      changes.push({
+        path,
+        state: 'not-in-current-template',
+        baselineSha256: baseline.get(path),
+        templateChanged: true,
+      });
+      continue;
+    }
     // Reject symlinks at every managed path component, without reading their destinations.
     let blocked = false;
     for (let index = 1; index <= path.split('/').length; index++) {
       const part = await exists(join(target, ...path.split('/').slice(0, index)));
-      if (part?.isSymbolicLink()) { blocked = true; break; }
+      if (part?.isSymbolicLink()) {
+        blocked = true;
+        break;
+      }
     }
     const item = blocked ? undefined : await exists(join(target, path));
     const actual = item?.isFile() ? hash(await readFile(join(target, path))) : undefined;
-    changes.push({ path, state: blocked ? 'symlink' : actual === undefined ? 'missing' : actual === baseline.get(path) ? 'unchanged' : 'modified',
-      baselineSha256: baseline.get(path), currentSha256: actual, templateSha256: currentTemplate.get(path), templateChanged: currentTemplate.get(path) !== baseline.get(path) });
+    changes.push({
+      path,
+      state: blocked
+        ? 'symlink'
+        : actual === undefined
+          ? 'missing'
+          : actual === baseline.get(path)
+            ? 'unchanged'
+            : 'modified',
+      baselineSha256: baseline.get(path),
+      currentSha256: actual,
+      templateSha256: currentTemplate.get(path),
+      templateChanged: currentTemplate.get(path) !== baseline.get(path),
+    });
   }
-  return { status: 'checked', target, installed: { template: receipt.template, sdk: receipt.sdk }, available: { template: { id: definition.template.id, revision: definition.template.revision }, sdk: { name: manifestName, version: resources.sdk.version } }, files: changes, changedFiles: [] };
+  return {
+    status: 'checked',
+    target,
+    installed: { template: receipt.template, sdk: receipt.sdk },
+    available: {
+      template: { id: definition.template.id, revision: definition.template.revision },
+      sdk: { name: manifestName, version: resources.sdk.version },
+    },
+    files: changes,
+    changedFiles: [],
+  };
 }
 const manifestName = '@jangts/agent-core';
+/**
+ * Create or check a generated application directory.
+ *
+ * @param args CLI arguments: `TARGET` plus optional flags described by `usage`.
+ * @param cwd Directory relative paths are resolved against; defaults to the process cwd.
+ * @returns A plan (`--write` omitted), a comparison (`--check`) or the creation result.
+ * @throws {TypeError} When arguments, names, the target or the source file are invalid.
+ * @throws {Error} When the template, receipt or SDK manifest is unsupported or inconsistent.
+ */
 export async function createApplication(args, cwd = process.cwd()) {
   const { target, values } = parse(args, cwd);
-  if (basename(target) === '.local') throw new TypeError('Choose an application directory outside the temporary .local directory itself');
+  if (basename(target) === '.local')
+    throw new TypeError(
+      'Choose an application directory outside the temporary .local directory itself',
+    );
   const resources = await resolveSdkResources(resolve(cwd, values['--sdk-from'] ?? '.'));
   const definition = await templateResources(resources, values['--template'] ?? 'node-ts');
   if (values['--check']) return compare(target, resources, definition);
   await emptyTarget(target);
-  const defaultName = basename(target).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[._-]+|[._-]+$/g, '') || 'agent-app';
-  const input = inputs(values['--name'] ?? defaultName, values['--purpose'] ?? '依据当前问题和获准读取的资料提供帮助。');
+  const defaultName =
+    basename(target)
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]+/g, '-')
+      .replace(/^[._-]+|[._-]+$/g, '') || 'agent-app';
+  const input = inputs(
+    values['--name'] ?? defaultName,
+    values['--purpose'] ?? '依据当前问题和获准读取的资料提供帮助。',
+  );
   const files = await render(resources, definition, input);
   let source;
   if (values['--source']) {
     const path = resolve(cwd, values['--source']);
-    const info = await lstat(path); if (!info.isFile() || info.isSymbolicLink() || info.size > 32000) throw new TypeError('Source must be a regular UTF-8 file within 32000 bytes');
-    const library = await import(pathToFileURL(join(dirname(resources.knowledgeLoader), 'source.mjs')));
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink() || info.size > 32000)
+      throw new TypeError('Source must be a regular UTF-8 file within 32000 bytes');
+    const library = await import(
+      pathToFileURL(join(dirname(resources.knowledgeLoader), 'source.mjs'))
+    );
     source = await library.readSuppliedSource(path, values['--id'], 32000);
     const knowledge = await import(pathToFileURL(resources.knowledgeLoader));
-    const policy = JSON.parse(files.find(file => file.path === 'knowledge/knowledge.config.json').bytes.toString('utf8'));
+    const policy = JSON.parse(
+      files.find((file) => file.path === 'knowledge/knowledge.config.json').bytes.toString('utf8'),
+    );
     knowledge.compileApplicationKnowledge([source.document], policy);
   }
-  const receipt = { schemaVersion: 1, template: { id: definition.template.id, revision: definition.template.revision },
-    sdk: { name: manifestName, version: resources.sdk.version }, inputs: input,
-    files: files.map(({ path, sha256 }) => ({ path, sha256 })) };
-  const plan = { status: 'planned', target, ...receipt, files: [...receipt.files, { path: receiptName }],
-    source: source ? { documentId: values['--id'], originalName: source.name, sha256: source.digest, status: 'candidate-only' } : null,
-    changedFiles: [], installedDependencies: false, modelCalled: false, published: false };
+  const receipt = {
+    schemaVersion: 1,
+    template: { id: definition.template.id, revision: definition.template.revision },
+    sdk: { name: manifestName, version: resources.sdk.version },
+    inputs: input,
+    files: files.map(({ path, sha256 }) => ({ path, sha256 })),
+  };
+  const plan = {
+    status: 'planned',
+    target,
+    ...receipt,
+    files: [...receipt.files, { path: receiptName }],
+    source: source
+      ? {
+          documentId: values['--id'],
+          originalName: source.name,
+          sha256: source.digest,
+          status: 'candidate-only',
+        }
+      : null,
+    changedFiles: [],
+    installedDependencies: false,
+    modelCalled: false,
+    published: false,
+  };
   if (!values['--write']) return plan;
-  const parent = dirname(target), temporary = join(parent, '.local');
+  const parent = dirname(target),
+    temporary = join(parent, '.local');
   await mkdir(parent, { recursive: true });
-  let madeTemporary = false, staging;
+  let madeTemporary = false,
+    staging;
   try {
-    try { await mkdir(temporary); madeTemporary = true; } catch (error) { if (error.code !== 'EEXIST') throw error; }
-    const info = await lstat(temporary); if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('Temporary directory must be a real directory');
+    try {
+      await mkdir(temporary);
+      madeTemporary = true;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+    }
+    const info = await lstat(temporary);
+    if (!info.isDirectory() || info.isSymbolicLink())
+      throw new Error('Temporary directory must be a real directory');
     staging = await mkdtemp(join(temporary, 'agent-core-create-'));
-    for (const file of files) { await mkdir(dirname(join(staging, file.path)), { recursive: true }); await writeFile(join(staging, file.path), file.bytes, { flag: 'wx' }); }
+    for (const file of files) {
+      await mkdir(dirname(join(staging, file.path)), { recursive: true });
+      await writeFile(join(staging, file.path), file.bytes, { flag: 'wx' });
+    }
     let candidate;
     if (source) {
       const snapshot = join(staging, '.local/initial-source', source.name);
-      await mkdir(dirname(snapshot), { recursive: true }); await writeFile(snapshot, source.bytes, { flag: 'wx' });
-      const output = await execute(process.execPath, [resources.tools['prepare-source'], join(staging, 'knowledge'), '--source', snapshot, '--id', values['--id']]);
+      await mkdir(dirname(snapshot), { recursive: true });
+      await writeFile(snapshot, source.bytes, { flag: 'wx' });
+      const output = await execute(process.execPath, [
+        resources.tools['prepare-source'],
+        join(staging, 'knowledge'),
+        '--source',
+        snapshot,
+        '--id',
+        values['--id'],
+      ]);
       candidate = relative(staging, JSON.parse(output.stdout).candidate);
-      if (!pathInside(candidate.split(sep).join('/'))) throw new Error('Candidate escaped the generated project');
+      if (!pathInside(candidate.split(sep).join('/')))
+        throw new Error('Candidate escaped the generated project');
       await rm(join(staging, '.local/initial-source'), { recursive: true });
       await rmdir(join(staging, '.local'));
     }
-    await writeFile(join(staging, receiptName), JSON.stringify({ ...receipt, createdAtMs: Date.now() }, null, 2) + '\n', { flag: 'wx' });
+    await writeFile(
+      join(staging, receiptName),
+      JSON.stringify({ ...receipt, createdAtMs: Date.now() }, null, 2) + '\n',
+      { flag: 'wx' },
+    );
     // Recheck before the atomic directory rename; a concurrent writer's non-empty target is preserved.
-    await emptyTarget(target); await rename(staging, target); staging = undefined;
-    return { ...plan, status: 'created', changedFiles: [...files.map(file => file.path), receiptName], ...(candidate ? { candidate: join(target, candidate) } : {}) };
+    await emptyTarget(target);
+    await rename(staging, target);
+    staging = undefined;
+    return {
+      ...plan,
+      status: 'created',
+      changedFiles: [...files.map((file) => file.path), receiptName],
+      ...(candidate ? { candidate: join(target, candidate) } : {}),
+    };
   } finally {
     if (staging) await rm(staging, { recursive: true });
     if (madeTemporary) await rmdir(temporary).catch(() => {});
   }
 }
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  try { console.log(JSON.stringify(await createApplication(process.argv.slice(2)), null, 2)); }
-  catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
+  try {
+    console.log(JSON.stringify(await createApplication(process.argv.slice(2)), null, 2));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
 }