@xioflow/kernel 0.1.5 → 0.3.0

package/README.md

@@ -4,9 +4,10 @@
 [![npm](https://img.shields.io/npm/v/@xioflow/kernel.svg)](https://www.npmjs.com/package/@xioflow/kernel)
 [![Node](https://img.shields.io/badge/Node.js-22.5%2B-green.svg)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
-[![Docs](https://img.shields.io/badge/spec-ARCHITECTURE.md-informational.svg)](./ARCHITECTURE.md)
+[![Docs (EN)](https://img.shields.io/badge/spec-ARCHITECTURE.en.md-informational.svg)](./ARCHITECTURE.en.md)
+[![Docs (ZH)](https://img.shields.io/badge/spec-ARCHITECTURE.md-informational.svg)](./ARCHITECTURE.md)
 
-A supervised execution kernel for AI agent runtimes. Zero runtime dependencies.
+A supervised execution kernel for AI agent runtimes. Zero runtime dependencies. (See [Architecture & Protocol Specification (EN)](./ARCHITECTURE.en.md) / [中文规范](./ARCHITECTURE.md)).
 
 Agent runtimes usually call `spawn()` (or `exec()`) and hope for the best. When the host crashes mid-tool-call, or a cancel cannot be confirmed, they are left with orphan processes, double-applied side effects, and no honest record of what actually happened. This kernel makes those states first-class instead of silent.
 
@@ -38,11 +39,41 @@ npm install @xioflow/kernel
 
 ## Quickstart
 
+### 1. Simplest Usage (`quickRun`)
+
+For standard tool calls and durable activity execution, `quickRun` automatically manages domain acquisition, Task and Run records, and lock lifecycles:
+
+```js
+import { quickRun } from '@xioflow/kernel';
+
+// 1. One-line supervised execution
+const result = await quickRun({
+  execPath: 'npm',
+  args: ['test'],
+  cwd: '/path/to/workspace',
+});
+
+console.log(result.status, result.exitCode, result.stdout);
+
+// 2. Idempotent execution (safe retry for Temporal / LangGraph / durable workflows)
+const idemResult = await quickRun(
+  { execPath: 'git', args: ['commit', '-m', 'chore: update'], cwd: '/path/to/workspace' },
+  { opId: 'workflow-step-42' } // Passing opId guarantees at-most-once execution across retries
+);
+if (idemResult.replayed) {
+  console.log('Result retrieved from journal without re-executing process');
+}
+```
+
+### 2. Full Architecture & Fine-Grained Supervision
+
+When you need granular control over Tasks, Runs, resource locks, streaming output, or multi-phase workflows:
+
 ```js
 import { ExecutionDomain, NodePlatformDriver, ProcessSupervisor } from '@xioflow/kernel';
 
 // The domain directory will hold domain.db, domain.lock and artifacts/.
-const domain = ExecutionDomain.acquire('/path/to/workspace/.xioflow', 'my-domain');
+const domain = ExecutionDomain.acquire('/path/to/workspace/.xioflow/kernel', 'my-domain');
 const supervisor = new ProcessSupervisor(domain, new NodePlatformDriver());
 
 // Every operation belongs to a Run, and every Run to a Task. Register them first:
@@ -89,6 +120,9 @@ domain.close(); // releases the owner lease and the domain lock
 
 To cancel, call `await supervisor.cancelOperation('op-1', graceMs)`. It returns `{ stopped, scope, residualPids? }`. The pending `executeProcess` promise then resolves with `status: 'cancelled'`, or with `status: 'indeterminate'` when the driver cannot confirm that the process actually stopped, in which case its leases stay locked.
 
+> **Note on In-Flight Join and Cancellation**:
+> When an in-flight operation with the same `opId` and fingerprint is joined concurrently, passing an `abortSignal` to the secondary caller only cancels the secondary caller's own wait promise—it never aborts the underlying process or the primary caller's execution. To deliberately terminate the underlying process, explicitly call `supervisor.cancelOperation(opId)`.
+
 ## Crash recovery
 
 After a restart, reacquire the domain and run the recovery engine:
@@ -96,7 +130,7 @@ After a restart, reacquire the domain and run the recovery engine:
 ```js
 import { ExecutionDomain, NodePlatformDriver, RecoveryEngine } from '@xioflow/kernel';
 
-const domain = ExecutionDomain.acquire('/path/to/workspace/.xioflow', 'my-domain');
+const domain = ExecutionDomain.acquire('/path/to/workspace/.xioflow/kernel', 'my-domain');
 const report = await new RecoveryEngine(domain, new NodePlatformDriver()).recover();
 ```
 
@@ -150,10 +184,21 @@ Releases are tag-driven. A tag always produces a GitHub Release; the npm upload
 
 1. Bump `version` in `package.json`, commit, and push to `main`.
 2. Push the matching tag, e.g. `git tag v0.1.5 && git push origin v0.1.5`.
-3. `.github/workflows/release.yml` re-runs typecheck, tests and the pack smoke test, refuses a tag that does not match `package.json`, creates the GitHub Release, and — only when the repository variable `NPM_TRUSTED_PUBLISHING_ENABLED` is `true` — publishes with `npm publish --provenance` and verifies the attestation.
+3. `.github/workflows/release.yml` re-runs typecheck, tests and the pack smoke test, refuses a tag that does not match `package.json`, creates the GitHub Release with the packed tarball, `SHA256SUMS` and a build provenance attestation attached, and — only when the repository variable `NPM_TRUSTED_PUBLISHING_ENABLED` is `true` — publishes with `npm publish --provenance` and verifies the attestation.
 
 One-time setup, in this order: (1) npmjs.com → package settings → Trusted Publisher → GitHub Actions: organization `Xio-Shark`, repository `xioflow`, workflow filename `release.yml`, environment left empty; (2) set the repository variable `NPM_TRUSTED_PUBLISHING_ENABLED=true`. Until both exist the publish job is skipped and the reason is printed in the `verify` job's log. npm's registry index can lag several minutes behind an upload, so the verification step polls and may need a job re-run.
 
+To attach assets to an existing tag without publishing to npm, run the workflow manually: `gh workflow run release.yml -f tag=v0.1.5`. An asset that is already attached is kept if identical and fails the run if it differs; published assets are never overwritten.
+
+### Verifying a release
+
+```bash
+gh release download v0.1.5 --repo Xio-Shark/xioflow
+shasum -a 256 -c SHA256SUMS
+gh attestation verify xioflow-kernel-0.1.5.tgz --repo Xio-Shark/xioflow
+npm audit signatures   # inside a project that installed @xioflow/kernel from npm
+```
+
 ## License
 
 MIT

package/dist/domain.d.ts

@@ -1,6 +1,25 @@
 import { SqliteStore } from './store/sqlite.js';
-import { Operation, OwnerRecord, ResourceBudget, DomainBudget, DomainLockedError, ResourceConflictError, EpochFencedError } from './types.js';
-export { DomainLockedError, ResourceConflictError, EpochFencedError };
+import { PlatformDriver } from './driver/types.js';
+import { Operation, ResourceLease, OwnerRecord, ResourceBudget, DomainBudget, DomainLockedError, ResourceConflictError, EpochFencedError, TerminationReason, AdjudicationRecord, Task, Run } from './types.js';
+export { DomainLockedError, ResourceConflictError, EpochFencedError, AdjudicationRecord };
+export interface DomainStatus {
+    domainId: string;
+    domainPath: string;
+    epoch: number;
+    owner: OwnerRecord;
+    tasks: Task[];
+    runs: Run[];
+    activeRuns: Run[];
+    operations: (Operation & {
+        domainId: string;
+    })[];
+    unfinishedOperations: (Operation & {
+        domainId: string;
+    })[];
+    leases: (ResourceLease & {
+        budget?: ResourceBudget;
+    })[];
+}
 export declare class ExecutionDomain {
     readonly domainPath: string;
     readonly domainId: string;
@@ -9,8 +28,11 @@ export declare class ExecutionDomain {
     private lockFd;
     private ownerRecord;
     private domainBudget?;
+    private driver?;
     private inMemoryLockedResources;
+    private inMemoryAllocatedOps;
     private inMemoryBudgets;
+    private waitQueue;
     private heartbeatInterval;
     private isFenced;
     private constructor();
@@ -20,6 +42,8 @@ export declare class ExecutionDomain {
     getEpoch(): number;
     setDomainBudget(budget: DomainBudget): void;
     getDomainBudget(): DomainBudget | undefined;
+    get status(): DomainStatus;
+    getStatus(): DomainStatus;
     /**
      * 启动时优先重建隔离屏障 (Recovery-Before-Execution)
      */
@@ -34,22 +58,52 @@ export declare class ExecutionDomain {
      * 刷新租约心跳，若失败则触发代际栅栏与写凭证销毁
      */
     renewHeartbeat(): void;
+    private getActiveOperationIds;
+    private diagnoseConflict;
     /**
      * 申请占用资源（支持隔离检查与配额校验）
      */
     allocateResources(operationId: string, resources: string[], waitedDurationMs?: number, budget?: ResourceBudget): void;
     /**
-     * 具备排队等待与诊断的异步资源分配
+     * 具备 FIFO 排队等待与诊断的异步资源分配 (P0-5, P0-13)
+     */
+    allocateResourcesWithWait(operationId: string, resources: string[], maxWaitMs?: number, budget?: ResourceBudget, isCancelled?: () => boolean): Promise<void>;
+    /**
+     * 取消在等待队列中的操作 (立即唤醒以完成取消协议)
+     */
+    cancelWait(operationId: string): boolean;
+    private processWaitQueue;
+    setDriver(driver: PlatformDriver): void;
+    /**
+     * 内部私有资源释放（走代际栅栏并记录 RESOURCES_RELEASED 事件，§0.2 裁决 1 / N6）
+     * @internal 仅供 supervisor、recovery engine 与 adjudicate 等内核内部组件调用
      */
-    allocateResourcesWithWait(operationId: string, resources: string[], maxWaitMs?: number, budget?: ResourceBudget): Promise<void>;
+    internalReleaseResources(operationId: string, resources?: string[]): void;
     /**
-     * 释放资源占用
+     * 人工裁决协议：对 indeterminate 状态进行有审计记录的唯一收口 (ARCHITECTURE §3.6 / P0-7)
      */
-    releaseResources(operationId: string, resources?: string[]): void;
+    adjudicate(opId: string, verdict: 'confirmed_stopped' | 'abandon_with_residuals', actor: string, note?: string): Promise<AdjudicationRecord>;
+    /**
+     * Run 完成与取消协议 (ARCHITECTURE §3.3)
+     */
+    reportRunCancelled(runId: string, reason?: TerminationReason): void;
+    reportRunSucceeded(runId: string): void;
+    reportRunFailed(runId: string, reason?: TerminationReason): void;
     /**
      * 意图登记协议：先持久化意图与占用，再允许驱动调用
      */
     registerOperationIntent(op: Operation): void;
+    /**
+     * 产物回收防线 (ARCHITECTURE §4.3 / N7)
+     * 只回收已终态且未被引用的产物，严格拒绝回收未终结或 indeterminate 状态的产物。
+     */
+    pruneArtifacts(filter?: {
+        olderThanMs?: number;
+        prefix?: string;
+    }): {
+        deleted: string[];
+        retained: string[];
+    };
     isClosed(): boolean;
     close(): void;
 }

package/dist/domain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../src/domain.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAEL,SAAS,EAET,WAAW,EACX,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,CAAC;AAEtE,qBAAa,eAAe;IAC1B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,YAAY,CAAC,CAAe;IAEpC,OAAO,CAAC,uBAAuB,CAAkC;IAEjE,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAkB;IAElC,OAAO,eAqCN;IAED,OAAc,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAkB,GAAG,eAAe,CAqDvF;IAED,OAAO,CAAC,MAAM,CAAC,iBAAiB;IASzB,cAAc,IAAI,WAAW,CAEnC;IAEM,QAAQ,IAAI,MAAM,CAExB;IAEM,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAEjD;IAEM,eAAe,IAAI,YAAY,GAAG,SAAS,CAEjD;IAED;;OAEG;IACI,yBAAyB,IAAI,IAAI,CAuBvC;IAEM,QAAQ,IAAI,WAAW,CAE7B;IAEM,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEnD;IAEM,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE9D;IAEM,qBAAqB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAElD;IAEM,cAAc,IAAI,OAAO,CAE/B;IAED,OAAO,CAAC,eAAe;IAWvB;;OAEG;IACI,cAAc,IAAI,IAAI,CAqB5B;IAED;;OAEG;IACI,iBAAiB,CACtB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EAAE,EACnB,gBAAgB,GAAE,MAAU,EAC5B,MAAM,CAAC,EAAE,cAAc,GACtB,IAAI,CA6BN;IAED;;OAEG;IACU,yBAAyB,CACpC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EAAE,EACnB,SAAS,GAAE,MAAU,EACrB,MAAM,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAkBf;IAED;;OAEG;IACI,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAiBvE;IAED;;OAEG;IACI,uBAAuB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAalD;IAEM,QAAQ,IAAI,OAAO,CAEzB;IAEM,KAAK,IAAI,IAAI,CAmCnB;CACF"}
+{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../src/domain.ts"],"names":[],"mappings":"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"}