@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/src/cli/release.ts

@@ -0,0 +1,117 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { buildInfoFromArtifact, requirePublishableArtifact } from '../runtime-identity.ts';
+import { commitForGitTag, canonicalTarballDigest, gitSourceSha, gitWorkingTreeStatus, packPackageTarball, removeTarballDirectory } from '../release-tarball.ts';
+import { SkillsRuntime } from '../toolkit.ts';
+import { parseCompatibilityDistTag, validatePublication } from '../release.ts';
+
+const packageRoot = resolve(fileURLToPath(new URL('../..', import.meta.url)));
+
+function repositoryRoot(): string {
+  return execFileSync('git', ['-C', packageRoot, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
+}
+
+function assertGitTagProvenance(sourceSha: string, version: string, repoRoot = repositoryRoot()): void {
+  const tag = `multi-task-flow-v${version}`;
+  let taggedSha: string;
+  try { taggedSha = commitForGitTag(repoRoot, tag); } catch { throw new Error(`Publication requires Git tag ${tag} at source SHA ${sourceSha}`); }
+  if (taggedSha !== sourceSha) throw new Error(`Publication Git tag does not point to artifact source: ${tag}`);
+}
+
+function parsePublicationArgs(args: string[]): { version?: string; distTag?: string; compatibilityLine?: string } {
+  let version: string | undefined;
+  let distTag: string | undefined;
+  let compatibilityLine: string | undefined;
+  for (let index = 0; index < args.length; index += 1) {
+    const option = args[index];
+    if (option === '--version') version = args[++index];
+    else if (option === '--dist-tag') distTag = args[++index];
+    else if (option === '--compatibility-line') compatibilityLine = args[++index];
+    else throw new Error(`Unknown release option: ${option}`);
+  }
+  return {
+    ...(version === undefined ? {} : { version }),
+    ...(distTag === undefined ? {} : { distTag }),
+    ...(compatibilityLine === undefined ? {} : { compatibilityLine }),
+  };
+}
+
+async function runPublishCommand(args: string[]): Promise<void> {
+  const options = parsePublicationArgs(args);
+  const packageMetadata = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf8')) as { version?: string };
+  const version = options.version ?? packageMetadata.version;
+  if (!version) throw new Error('Missing package version');
+  const publication = validatePublication(version, options.distTag);
+  const repoRoot = repositoryRoot();
+  if (gitWorkingTreeStatus(repoRoot).trim()) throw new Error('Publication requires a clean Git checkout');
+  const sourceSha = gitSourceSha(repoRoot);
+  assertGitTagProvenance(sourceSha, version, repoRoot);
+  const gitTag = `multi-task-flow-v${version}`;
+  const buildScript = resolve(repoRoot, 'skills/multi-task-flow/scripts/package-client-skills.ts');
+  const buildEnvironment = (tarballDigest = '') => ({ ...process.env, LOOMHELM_REQUIRE_MERGE_SHA: '1', LOOMHELM_MERGE_SHA: sourceSha, LOOMHELM_GIT_TAG: gitTag, LOOMHELM_TARBALL_DIGEST: tarballDigest });
+  const build = (tarballDigest = '') => execFileSync(process.execPath, ['--no-install', buildScript, '--require-dependencies'], { cwd: packageRoot, env: buildEnvironment(tarballDigest), stdio: 'inherit' });
+  const tarballs: string[] = [];
+  try {
+    build();
+    const draft = packPackageTarball(packageRoot);
+    tarballs.push(draft);
+    const digest = canonicalTarballDigest(draft);
+    build(digest);
+    const finalTarball = packPackageTarball(packageRoot);
+    tarballs.push(finalTarball);
+    if (canonicalTarballDigest(finalTarball) !== digest) throw new Error('Tarball digest changed after embedding provenance');
+    const artifact = await new SkillsRuntime().validate();
+    const identity = requirePublishableArtifact(artifact);
+    if (identity.packageVersion !== version || identity.tarballDigest !== digest) throw new Error('Packaged provenance does not match the publication request');
+    if (options.compatibilityLine !== undefined && options.compatibilityLine !== identity.compatibilityLine) throw new Error('Declared compatibility line does not match artifact identity');
+    execFileSync(process.execPath, ['publish', '--tag', publication.distTag, finalTarball], { cwd: packageRoot, env: buildEnvironment(digest), stdio: 'inherit' });
+    console.log(JSON.stringify({ ...publication, packageName: identity.packageName, sourceSha, mergeSha: identity.mergeSha, buildId: identity.buildId, tarballDigest: digest, gitTag }));
+  } finally {
+    for (const tarball of tarballs) removeTarballDirectory(tarball);
+  }
+}
+
+export async function runReleaseCommand(args: string[]): Promise<void> {
+  if (args[0] === 'help' || !args.length) {
+    console.log('release identity | validate --version VERSION [--dist-tag VERSION|compat-vN] [--compatibility-line compat-vN] [--require-provenance] | publish [--version VERSION] --dist-tag VERSION|compat-vN [--compatibility-line compat-vN]');
+    return;
+  }
+  if (args[0] === 'publish') { await runPublishCommand(args.slice(1)); return; }
+  const artifact = await new SkillsRuntime().validate();
+  const buildInfo = buildInfoFromArtifact(artifact);
+  if (args[0] === 'identity' && args.length === 1) {
+    console.log(JSON.stringify(buildInfo));
+    return;
+  }
+  if (args[0] !== 'validate') throw new Error('Usage: release identity | validate --version VERSION [--dist-tag VERSION|compat-vN] [--compatibility-line compat-vN] [--require-provenance] | publish [--version VERSION] --dist-tag VERSION|compat-vN [--compatibility-line compat-vN]');
+  const publicationArgs = parsePublicationArgs(args.slice(1).filter(option => option !== '--require-provenance'));
+  let version = publicationArgs.version;
+  let distTag = publicationArgs.distTag;
+  let compatibilityLine = publicationArgs.compatibilityLine;
+  let requireProvenance = false;
+  requireProvenance = args.includes('--require-provenance');
+  if (!version) throw new Error('Missing --version');
+  if (version !== buildInfo.version) throw new Error(`Publication version does not match artifact version: ${version}`);
+  if (compatibilityLine !== undefined && compatibilityLine !== buildInfo.compatibility_line) throw new Error('Declared compatibility line does not match artifact identity');
+  if (requireProvenance) {
+    const identity = requirePublishableArtifact(artifact);
+    assertGitTagProvenance(identity.sourceSha, identity.packageVersion);
+  }
+  const publication = validatePublication(version, distTag);
+  const declaredLine = buildInfo.compatibility_line;
+  if (declaredLine) {
+    parseCompatibilityDistTag(declaredLine);
+    if (distTag && distTag !== version && distTag !== declaredLine) throw new Error('Publication dist-tag does not match the declared compatibility line');
+  }
+  console.log(JSON.stringify({
+    ...publication,
+    packageName: buildInfo.package_name,
+    compatibilityLine: declaredLine,
+    sourceSha: buildInfo.source_sha,
+    mergeSha: buildInfo.merge_sha,
+    buildId: buildInfo.build_id,
+    tarballDigest: buildInfo.tarball_digest,
+  }));
+}

package/src/cli/skills.ts

@@ -0,0 +1,20 @@
+import { SkillsRuntime } from '../toolkit.ts';
+
+export async function runSkillsCommand(args: string[]): Promise<void> {
+  const runtime = new SkillsRuntime();
+  if (args[0] === 'list' && args.length === 1) { console.log(JSON.stringify(await runtime.list())); return; }
+  if (args[0] === 'check' && args.length === 2) { const result = await runtime.check(args[1]!); console.log(JSON.stringify(result)); if (!result.ready) process.exitCode = 3; return; }
+  if (args[0] === 'run' && args[1]) {
+    // Preserve stdin and the original JSON/exit-code contract. Authorization for
+    // specialty scripts remains a caller obligation, as documented by each Skill.
+    const chunks: Buffer[] = []; let size = 0;
+    for await (const chunk of (process.stdin.isTTY ? [] : process.stdin)) {
+      const bytes = Buffer.from(chunk); size += bytes.length;
+      if (size > 16 * 1024 * 1024) throw new Error('Skill input too large');
+      chunks.push(bytes);
+    }
+    const result = await runtime.run(args[1], args.slice(2), { input: Buffer.concat(chunks) });
+    process.stdout.write(result.stdout); process.stderr.write(result.stderr); process.exitCode = result.code ?? 1; return;
+  }
+  throw new Error('Usage: skills list | check NAME | run SCRIPT [ARGS...]');
+}

package/src/cli.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env -S bun --no-install
+import { LocalClient } from './client.ts';
+import { StateLock } from './runtime/lock.ts';
+import { loadConfig } from './config.ts';
+import { GitAdapter } from './git.ts';
+import { runProcess } from './runtime/process.ts';
+import type { Operation } from './tasks/model.ts';
+import { runCodexCommand } from './cli/codex.ts';
+import { runSkillsCommand } from './cli/skills.ts';
+import { runFlowCommand } from './cli/flow.ts';
+import { runReleaseCommand } from './cli/release.ts';
+import { buildInfoFromArtifact } from './runtime-identity.ts';
+import { SkillsRuntime } from './toolkit.ts';
+import { fileURLToPath } from 'node:url';
+
+async function main(args: string[]): Promise<void> {
+  if (args.length === 1 && (args[0] === "--version" || args[0] === "version")) { console.log(JSON.stringify(buildInfoFromArtifact(await new SkillsRuntime().validate()))); return; }
+  let configPath: string | undefined;
+  if (args[0] === '--config') { args.shift(); configPath = args.shift(); if (!configPath) throw new Error('Missing config path'); }
+  const [command, ...rest] = args;
+  if (command === 'help' || !command) {
+    console.log('multi-task-flow [--config PATH] status|tasks|receipts|recover-lock TOKEN|apply OPERATION_ID JSON|run OPERATION_ID TASK_ID COMMAND_JSON|git-status PATH|worktree REPO ABS_PATH BRANCH [BASE]|codex COMMAND ...|flow COMMAND ...|skills COMMAND ...|release COMMAND ...|workflow COMMAND ...'); return;
+  }
+  if (command === 'skills') { await runSkillsCommand(rest); return; }
+  if (command === 'codex') { await runCodexCommand(rest, configPath); return; }
+  if (command === 'flow') { await runFlowCommand(rest, configPath); return; }
+  if (command === 'release') { await runReleaseCommand(rest); return; }
+  if (command === 'workflow') {
+    if (rest[0] === 'verify') throw new Error('WORKFLOW_LEGACY_COMMAND_UNSUPPORTED: use local-verify for local validation only; follow the migrated engineering Skills for delivery gates');
+    if (!rest.length) throw new Error('Usage: workflow skills PROJECT_SKILLS_DIR [USER_SKILLS_DIR] | local-verify MANIFEST_JSON_PATH');
+    const result = await runProcess(process.execPath, ['--no-install', fileURLToPath(new URL('./workflow/cli.ts', import.meta.url)), ...rest]);
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    if (result.code !== 0) process.exitCode = result.code ?? 1;
+    return;
+  }
+  if (command === 'recover-lock' && rest.length === 1) { await StateLock.recover((await loadConfig(configPath)).stateDir, rest[0]!); console.log(JSON.stringify({ recovered: true })); return; }
+  if (command === 'git-status' && rest.length === 1) { console.log(JSON.stringify(await new GitAdapter(rest[0]!).inspect())); return; }
+  if (command === 'worktree' && (rest.length === 3 || rest.length === 4)) {
+    console.log(JSON.stringify(await new GitAdapter(rest[0]!).createWorktree(rest[1]!, rest[2]!, rest[3]))); return;
+  }
+  if (!['status', 'tasks', 'receipts', 'apply', 'run'].includes(command) || (command === 'apply' ? rest.length !== 2 : command === 'run' ? rest.length !== 3 : rest.length !== 0)) throw new Error('Invalid command; see help');
+  const client = await LocalClient.open(configPath);
+  const controller = new AbortController();
+  const interrupt = () => { controller.abort(); process.exitCode = 130; };
+  process.once('SIGINT', interrupt); process.once('SIGTERM', interrupt);
+  try {
+    let output: unknown;
+    switch (command) {
+      case 'status': output = { mode: client.config.mode, stateDir: client.config.stateDir, tasks: Object.keys(client.ledger.snapshot().tasks).length }; break;
+      case 'tasks': output = client.ledger.snapshot(); break;
+      case 'receipts': output = client.ledger.history(); break;
+      case 'run': {
+        const [operationId, taskId, encoded] = rest as [string, string, string];
+        if (operationId.length > 80) throw new Error('Run operation identity is too long');
+        const argv: unknown = JSON.parse(encoded);
+        if (!Array.isArray(argv) || !argv.length || argv.some(arg => typeof arg !== 'string') || !argv[0]) throw new Error('Command must be a nonempty string array');
+        const runId = `${operationId}.run`;
+        const start = { type: 'run.start' as const, taskId, runId, command: argv as string[] };
+        const existing = client.ledger.history().find(r => r.operationId === `${operationId}.start`);
+        await client.ledger.execute(`${operationId}.start`, start);
+        if (existing) {
+          const finished = client.ledger.history().find(r => r.operationId === `${operationId}.finish`);
+          if (!finished) throw new Error('Uncertain previous execution; inspect receipts before explicit retry with a new identity');
+          output = finished;
+          if (finished.operation.type === 'run.finish' && finished.operation.status !== 'succeeded') process.exitCode = 1;
+          break;
+        }
+        let status: 'succeeded' | 'failed' | 'interrupted' = 'failed';
+        let detail: string;
+        try {
+          const result = await runProcess(argv[0], argv.slice(1), {
+            ...(client.ledger.snapshot().tasks[taskId]?.repository ? { cwd: client.ledger.snapshot().tasks[taskId]!.repository! } : {}),
+            timeoutMs: client.config.processTimeoutMs, signal: controller.signal,
+          });
+          status = result.code === 0 ? 'succeeded' : 'failed';
+          detail = JSON.stringify(result);
+        } catch (error) {
+          status = controller.signal.aborted ? 'interrupted' : 'failed';
+          detail = error instanceof Error ? error.message : String(error);
+        }
+        output = await client.ledger.execute(`${operationId}.finish`, { type: 'run.finish', runId, status, detail });
+        if (status !== 'succeeded') process.exitCode = controller.signal.aborted ? 130 : 1;
+        break;
+      }
+      case 'apply': output = await client.ledger.execute(rest[0]!, JSON.parse(rest[1]!) as Operation); break;
+    }
+    console.log(JSON.stringify(output));
+  } finally {
+    await client.close(); process.removeListener('SIGINT', interrupt); process.removeListener('SIGTERM', interrupt);
+  }
+}
+main(process.argv.slice(2)).catch(error => { console.error(JSON.stringify({ code: 'CLI_ERROR', error: error instanceof Error ? error.message : String(error) })); process.exitCode = 1; });

package/src/client.ts

@@ -0,0 +1,83 @@
+import { type ClientConfig, loadConfig } from './config.ts';
+import { Ledger } from './tasks/ledger.ts';
+import { runProcess, type ProcessOptions } from './runtime/process.ts';
+import type { Receipt } from './tasks/ledger.ts';
+
+export interface TaskRunOptions extends Omit<ProcessOptions, 'timeoutMs' | 'maxOutputBytes'> {
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+}
+
+export class LocalClient {
+  private readonly active = new Set<AbortController>();
+  private readonly runs = new Set<Promise<Receipt>>();
+  private readonly requests = new Map<string, { taskId: string; command: string[]; promise: Promise<Receipt> }>();
+  private closing = false;
+  private constructor(readonly config: ClientConfig, readonly ledger: Ledger) {}
+  static async open(configPath?: string): Promise<LocalClient> {
+    const config = await loadConfig(configPath);
+    return new LocalClient(config, await Ledger.open(config.stateDir));
+  }
+  /** Execute one task attempt and persist its outcome before returning. */
+  runTask(operationId: string, taskId: string, command: readonly string[], options: TaskRunOptions = {}): Promise<Receipt> {
+    if (this.closing) return Promise.reject(new Error('Client is closed'));
+    if (!Array.isArray(command) || command.length === 0 || command.some(arg => typeof arg !== 'string') || !command[0]) return Promise.reject(new Error('Invalid task command'));
+    const previous = this.requests.get(operationId);
+    if (previous) {
+      if (previous.taskId !== taskId || JSON.stringify(previous.command) !== JSON.stringify(command)) return Promise.reject(new Error('Operation identity conflict'));
+      return previous.promise;
+    }
+    const controller = new AbortController();
+    const forwardAbort = () => controller.abort();
+    options.signal?.addEventListener('abort', forwardAbort, { once: true });
+    this.active.add(controller);
+    const promise = this.executeTask(operationId, taskId, command, options, controller.signal)
+      .finally(() => { options.signal?.removeEventListener('abort', forwardAbort); this.active.delete(controller); });
+    this.requests.set(operationId, { taskId, command: [...command], promise });
+    this.runs.add(promise);
+    void promise.then(() => this.runs.delete(promise), () => this.runs.delete(promise));
+    return promise;
+  }
+
+  private async executeTask(operationId: string, taskId: string, command: readonly string[], options: TaskRunOptions, signal: AbortSignal): Promise<Receipt> {
+    const startId = `${operationId}.start`;
+    const finishId = `${operationId}.finish`;
+    const priorStart = this.ledger.history().find(receipt => receipt.operationId === startId);
+    await this.ledger.execute(startId, { type: 'run.start', taskId, runId: `${operationId}.run`, command: [...command] });
+    if (priorStart) {
+      const priorFinish = this.ledger.history().find(receipt => receipt.operationId === finishId);
+      if (!priorFinish) throw new Error('Uncertain previous execution; inspect receipts before retrying');
+      return priorFinish;
+    }
+    let status: 'succeeded' | 'failed' | 'interrupted' = 'failed';
+    let detail: string;
+    try {
+      const task = this.ledger.snapshot().tasks[taskId];
+      const processOptions: ProcessOptions = {
+        timeoutMs: options.timeoutMs ?? this.config.processTimeoutMs,
+        maxOutputBytes: options.maxOutputBytes ?? this.config.maxOutputBytes,
+        signal,
+      };
+      const cwd = options.cwd ?? task?.repository;
+      if (cwd !== undefined) processOptions.cwd = cwd;
+      if (options.env !== undefined) processOptions.env = options.env;
+      const result = await runProcess(command[0]!, command.slice(1), processOptions);
+      status = result.code === 0 ? 'succeeded' : 'failed';
+      detail = JSON.stringify(result);
+    } catch (error) {
+      status = signal.aborted ? 'interrupted' : 'failed';
+      detail = error instanceof Error ? error.message : String(error);
+    }
+    return this.ledger.execute(finishId, { type: 'run.finish', runId: `${operationId}.run`, status, detail });
+  }
+
+  async close(): Promise<void> {
+    if (this.closing) { await Promise.allSettled(this.runs); return; }
+    this.closing = true;
+    for (const controller of this.active) controller.abort();
+    await Promise.allSettled(this.runs);
+    await this.ledger.close();
+  }
+
+  async stop(): Promise<void> { await this.close(); }
+}

package/src/codex/LICENSE-CODEX

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright 2025 OpenAI
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/src/codex/README.md

@@ -0,0 +1,60 @@
+# Codex app-server 适配
+
+本模块在 Bun 1.4.4 中使用标准 API，通过独立子进程的 stdio NDJSON 连接本机 Codex app-server；调用入口为源码 `src/codex/index.ts`，不依赖 Loomhelm 服务端、Web App 。只有显式调用 `CodexAppServer.start()` 才启动进程。
+
+协议来源为本机 `codex-cli 0.166.0` 的 `codex app-server generate-ts` 稳定输出和 [官方 app-server 文档](https://developers.openai.com/codex/app-server)。`protocol.ts` 保存所用参数、响应、服务器请求及依赖的生成类型；生成脚本只移除重复生成头和内部 import，将依赖闭包合并为一个文件，不自行推断字段。升级协议时，在本包目录执行 `bun src/codex/generate-protocol.ts`，审核差异并重跑行为测试。服务器仍使用已有本机 Codex 配置与凭据；适配器不读取、复制或上传凭据。
+
+## 调用与生命周期
+
+```ts
+import { CodexAppServer } from './src/codex/index.ts';
+
+const codex = await CodexAppServer.start({
+  onEvent(event, value) {
+    // Persist/route events and approval requests in the owning application.
+  },
+});
+try {
+  const { thread } = await codex.startThread({ cwd: '/absolute/repository' });
+  const { turn } = await codex.startTurn({
+    threadId: thread.id,
+    input: [{ type: 'text', text: 'Inspect the project', text_elements: [] }],
+  });
+  // This response acknowledges a turn; track turn/completed independently.
+} finally {
+  await codex.stop();
+}
+```
+
+`start()` 等待 `initialize` 响应，再发送不带 ID 的 `initialized` 通知，之后才交付 ready 实例。`command`、参数数组、cwd、env 和初始化身份可显式传入；不经过 shell。默认继承本机环境。初始化失败会停止已创建的进程。`state` 与 `pid` 提供当前进程身份；`stop()` 可重复调用，先结束 stdin，超过宽限期后仅向直接拥有的子进程发送 TERM/KILL，并等待真实 close。模块不负责子进程派生的后台服务或进程树。
+
+支持 `startThread`、`resumeThread`、`forkThread`、`readThread`、`listThreads`、`listTurns`、`setThreadName`、`startTurn`、`interruptTurn` 和 `listModels`；参数与分页游标保持官方格式。线程配置中的 reasoning effort 使用 `config.model_reasoning_effort`，turn 使用 `effort`。方法返回服务器响应，不自动推进任务状态。turn 启动响应与 turn 最终完成是两个不同事实，只有 `turn/completed.params.turn.status === 'completed'` 表示成功，`failed` 和 `interrupted` 必须由上层分别处理。
+
+## 事件和审批边界
+
+`onEvent` 在初始化前已连接，适合承接早期通知和服务器请求；实例的 `on()` 可追加订阅并返回取消订阅函数。`notification` 按接收顺序保留方法名与 params，包括未知通知、重复事件、工具调用、文件引用、文本 delta 和执行结果。UTF-8 数据按完整换行帧解码。此层没有事件去重、终态缓存或持久化回放，不会丢弃早于启动响应到达的完成通知；上层必须在启动 turn 前接入事件处理。
+
+带 ID 的服务器消息通过 `serverRequest` 显式转交，包含原始 `id`、`method`、`params` 和一次性 `respond(result)` / `reject(error)`。`approval` 标识命令、文件、权限及兼容旧协议审批；工具输入、动态工具、认证刷新和未知服务器请求也显式转交，由调用方决定处理或返回官方 RPC 错误。适配器不自动接受、拒绝、代填审批或执行工具。无人处理的请求保持待决，达到容量上限才关闭连接。调用方必须提供审批展示、授权与答复策略；错误的本地答复不会被默认解释为批准。
+
+答复写入管道成功只表示本地写入完成，不代表服务端已经接受。每个句柄只能答复一次；断连和 `serverRequest/resolved` 会使旧句柄失效。答复发送失败关闭连接，禁止使用旧句柄重试。事件处理器同步异常和异步拒绝通过 `handlerError` 交出，不破坏请求响应关联。`stderr` 是瞬时诊断流，模块不留存；调用方应按自身敏感信息政策处理。
+
+## 断连、超时与恢复
+
+请求 ID 使用连接随机身份与序号关联，允许并发和乱序响应，客户端与服务器请求的 ID 空间分开。`CodexRequestError` 保留 `requestId`、`method`、`outcome` 和可用的 `rpcError`：
+
+- `not-sent`：本地序列化、帧大小或待决请求容量检查失败，尚未发送。
+- `rejected`：收到对应 RPC 错误，保留 code、message 和 data。
+- `unknown`：写入开始后超时、断连、停止或收到无效响应，不能推定外部操作失败。
+
+超时只结束本地等待，不取消服务端操作；迟到或重复响应通过 `orphanResponse` 交出。断连会拒绝全部待决请求、撤销审批句柄并清理内存。非法 RPC 信封、必要身份形状错误、过大帧、stdout EOF 和进程异常也触发关闭；未知通知保留兼容性。默认单帧上限 8 MiB，每个方向各最多 1024 个待决请求，请求默认超时 30 秒，停止宽限期为 500 毫秒，可用 options 调整。
+
+恢复必须由上层显式启动新实例、完成握手，并使用已保存的 thread ID 执行 `readThread`、`listTurns` 或 `resumeThread` 对账。模块不自动重放 `thread/start`、`thread/fork` 或 `turn/start`，避免 ACK 丢失后重复创建工作。Loomhelm Task、Run、operation identity 与 Codex thread/turn 的持久关联、跨进程事件游标和业务重试策略属于 dispatch/orchestration 的账本边界，本模块只传递协议身份和不确定性。
+
+## 验证
+
+```sh
+bun run check
+bun run test
+```
+
+`test/codex.test.ts` 使用独立 Bun 伪服务器，在实际 Bun 进程中运行同一适配实现。覆盖握手、请求乱序、官方方法和参数转发、拆分 UTF-8、重复事件、启动响应前的终态、审批显式答复和失效、RPC 错误、超时与迟到响应、帧和请求容量上限、非法响应、断连与 stdout EOF、监听器异常、启动失败以及忽略 TERM 的进程回收。测试不启动真实 Codex、不调用模型、不使用账号或网络。