@theokit/cli 3.0.2 → 4.0.1

package/dist/index.d.cts

@@ -1,28 +1,145 @@
+import { Agent } from '@theokit/sdk';
+
+/**
+ * The shape of `eval.config.{ts,mjs}`, consumed by `theokit eval` (T5.1, ADR D199).
+ *
+ * ```ts
+ * import type { EvalConfig } from "@theokit/cli";
+ *
+ * export default {
+ *   agent: { model: "gpt-4o-mini" },
+ *   dataset: [{ input: "2+2?", expected: "4" }],
+ *   scorers: [{ name: "exact", score: (out, exp) => ({ score: out.trim() === exp ? 1 : 0 }) }],
+ * } satisfies EvalConfig;
+ * ```
+ *
+ * The runner now delegates to the SDK's `Eval.create().run()` (D212); this shape survived that swap
+ * unchanged, which is what D199 was for.
+ *
+ * @public
+ */
+
+/**
+ * Outcome of a single scoring decision.
+ *
+ * Exported because `Scorer` — which IS public — returns it: a user writing a scorer could not name
+ * its return type. Same shape as the `MemoryProviderFactory` defect in #335, one level down.
+ */
+interface Score {
+    /** Numeric score in [0, 1]. Use 1.0 for "pass", 0.0 for "fail". */
+    readonly score: number;
+    /** Optional human-readable reason for the score (shown in the report). */
+    readonly reason?: string;
+}
+/**
+ * Grades one agent output. May be sync or async (EC-K); both are awaited.
+ *
+ * `expected` is whatever the dataset entry carried, `unknown` because nothing constrains it — narrow
+ * it yourself. It is `undefined` for entries that declared no `expected`, so a scorer that assumes a
+ * string has to handle that.
+ *
+ * Scoring runs inside the SDK's eval engine, which reports per-ROW failures: a failed row carries an
+ * `error` and is counted in `errorRows` rather than aborting the suite.
+ */
+type Scorer = (output: string, expected?: unknown) => Score | Promise<Score>;
+/**
+ * One evaluation case: the prompt sent to the agent, and an optional expected value handed to every
+ * scorer untouched (no comparison is performed for you).
+ */
+interface DatasetEntry {
+    readonly input: string;
+    readonly expected?: unknown;
+}
+/**
+ * The `Agent.create()` options object, inferred from the installed `@theokit/sdk` rather than
+ * re-declared. Whatever that version accepts — model, tools, plugins — is accepted here.
+ */
+type EvalAgentOptions = Parameters<typeof Agent.create>[0];
+/**
+ * The DEFAULT export of `eval.config.{ts,mjs}`. A named export is not read.
+ *
+ * `theokit eval` checks only that `dataset` and `scorers` are arrays and `agent` is an object; every
+ * deeper mistake surfaces at run time, from the SDK, per row. An empty `dataset` is accepted and
+ * short-circuits to a zero-row report — the run costs nothing and proves nothing.
+ *
+ * Running it spends real money: each entry is one live agent turn against the configured provider.
+ */
+interface EvalConfig {
+    /** Cases to run, in order. Empty is legal and produces an empty report. */
+    readonly dataset: ReadonlyArray<DatasetEntry>;
+    /** Scorers applied to EVERY row. `name` is the column label in the markdown report. */
+    readonly scorers: ReadonlyArray<{
+        readonly name: string;
+        readonly score: Scorer;
+    }>;
+    /** Options for the agent under test — one agent config for the whole suite. */
+    readonly agent: EvalAgentOptions;
+    /**
+     * Rows evaluated in parallel. Omitted means the key is not forwarded at all, so the SDK's own
+     * default applies. Raise it and you raise your provider rate-limit exposure with it.
+     */
+    readonly concurrency?: number;
+}
+
 /**
  * Top-level CLI dispatcher via commander (ADR D194).
  *
- * Subcommands: `init`, `dev`, `inspect`, `eval`, `setup`, `acp`, `tasks`.
+ * Subcommands: `init`, `dev`, `inspect`, `eval`, `acp`, `setup`, `db`, `tasks`.
  *
- * Exit codes:
- *  - 0  → success
- *  - 1  → unknown error
- *  - 2  → user error (bad flags, unknown subcommand suggestion)
+ * Exit codes at this layer:
+ *  - 0  → success, and also `--help` / `--version`
+ *  - 1  → unknown error (an exception that escaped a subcommand)
+ *  - 2  → user error (unknown subcommand, unknown option, bad flag value)
+ *
+ * Subcommands are free to return codes of their own beyond these — `theokit tasks` uses 3 and 4,
+ * `theokit db check-schema-drift` uses 1 to mean "drift found", and `theokit dev` forwards the
+ * child process's exit code verbatim. Each command module documents its own.
  *
  * @internal
  */
+/**
+ * Parse `argv` and run the matching subcommand, returning the process exit code instead of exiting.
+ *
+ * `argv` is commander-shaped, i.e. the full `process.argv`: `[execPath, scriptPath, ...args]`. The
+ * first two entries are skipped, so passing `["theokit", "init"]` silently drops `init` — pass
+ * `["node", "theokit", "init"]` when synthesising one.
+ *
+ * Never throws and never calls `process.exit`; the caller decides what to do with the code (the
+ * bundled `bin/theokit.ts` shim exits with it). Writes to `process.stdout` and `process.stderr`
+ * directly, so redirect the streams if you need to capture the output.
+ *
+ * Returns `0` for success and for `--help` / `--version`, `2` for a user error, `1` for anything
+ * that escaped a subcommand as an exception, and otherwise whatever the subcommand returned.
+ */
 declare function main(argv: ReadonlyArray<string>): Promise<number>;
 
 /**
  * Build-time version constants for @theokit/cli.
  *
- * `__SDK_VERSION__` is the sibling `@theokit/sdk` semver (NEVER
- * `workspace:*` — resolved at build time via tsup `define`). Used by
- * `init` templates to pin the SDK dep in scaffolded projects (EC-L
- * fix from edge-case review).
+ * Both are substituted by tsup `define` at BUILD time, so they are plain string literals in the
+ * shipped bundle. The `declare const` below only satisfies the type checker: evaluating this module
+ * from unbuilt source, without that substitution, throws a ReferenceError at import.
+ *
+ * `__SDK_VERSION__` is the sibling `@theokit/sdk` semver (NEVER `workspace:*`). Used by `init`
+ * templates to pin the SDK dep in scaffolded projects (EC-L fix from edge-case review).
  *
  * `__CLI_VERSION__` is this package's semver. Exposed via `--version`.
  */
+/**
+ * The `@theokit/sdk` semver this CLI was BUILT against — a concrete version, never `workspace:*`.
+ *
+ * `theokit init` writes it into the scaffolded `package.json`, so it is what a new project pins. It
+ * is not a claim about the SDK the current process has loaded, which may be a different version
+ * entirely.
+ */
 declare const SDK_VERSION: string;
+/**
+ * This package's semver, substituted at build time — what `theokit --version` prints.
+ *
+ * Distinct from {@link SDK_VERSION}, which is the `@theokit/sdk` version this CLI was built against
+ * and the one `theokit init` writes into a scaffolded `package.json`. They move independently, so a
+ * bug report should quote both.
+ */
 declare const CLI_VERSION: string;
 
-export { CLI_VERSION, SDK_VERSION, main };
+export { CLI_VERSION, type DatasetEntry, type EvalConfig, SDK_VERSION, type Score, type Scorer, main };

package/dist/index.d.ts

@@ -1,28 +1,145 @@
+import { Agent } from '@theokit/sdk';
+
+/**
+ * The shape of `eval.config.{ts,mjs}`, consumed by `theokit eval` (T5.1, ADR D199).
+ *
+ * ```ts
+ * import type { EvalConfig } from "@theokit/cli";
+ *
+ * export default {
+ *   agent: { model: "gpt-4o-mini" },
+ *   dataset: [{ input: "2+2?", expected: "4" }],
+ *   scorers: [{ name: "exact", score: (out, exp) => ({ score: out.trim() === exp ? 1 : 0 }) }],
+ * } satisfies EvalConfig;
+ * ```
+ *
+ * The runner now delegates to the SDK's `Eval.create().run()` (D212); this shape survived that swap
+ * unchanged, which is what D199 was for.
+ *
+ * @public
+ */
+
+/**
+ * Outcome of a single scoring decision.
+ *
+ * Exported because `Scorer` — which IS public — returns it: a user writing a scorer could not name
+ * its return type. Same shape as the `MemoryProviderFactory` defect in #335, one level down.
+ */
+interface Score {
+    /** Numeric score in [0, 1]. Use 1.0 for "pass", 0.0 for "fail". */
+    readonly score: number;
+    /** Optional human-readable reason for the score (shown in the report). */
+    readonly reason?: string;
+}
+/**
+ * Grades one agent output. May be sync or async (EC-K); both are awaited.
+ *
+ * `expected` is whatever the dataset entry carried, `unknown` because nothing constrains it — narrow
+ * it yourself. It is `undefined` for entries that declared no `expected`, so a scorer that assumes a
+ * string has to handle that.
+ *
+ * Scoring runs inside the SDK's eval engine, which reports per-ROW failures: a failed row carries an
+ * `error` and is counted in `errorRows` rather than aborting the suite.
+ */
+type Scorer = (output: string, expected?: unknown) => Score | Promise<Score>;
+/**
+ * One evaluation case: the prompt sent to the agent, and an optional expected value handed to every
+ * scorer untouched (no comparison is performed for you).
+ */
+interface DatasetEntry {
+    readonly input: string;
+    readonly expected?: unknown;
+}
+/**
+ * The `Agent.create()` options object, inferred from the installed `@theokit/sdk` rather than
+ * re-declared. Whatever that version accepts — model, tools, plugins — is accepted here.
+ */
+type EvalAgentOptions = Parameters<typeof Agent.create>[0];
+/**
+ * The DEFAULT export of `eval.config.{ts,mjs}`. A named export is not read.
+ *
+ * `theokit eval` checks only that `dataset` and `scorers` are arrays and `agent` is an object; every
+ * deeper mistake surfaces at run time, from the SDK, per row. An empty `dataset` is accepted and
+ * short-circuits to a zero-row report — the run costs nothing and proves nothing.
+ *
+ * Running it spends real money: each entry is one live agent turn against the configured provider.
+ */
+interface EvalConfig {
+    /** Cases to run, in order. Empty is legal and produces an empty report. */
+    readonly dataset: ReadonlyArray<DatasetEntry>;
+    /** Scorers applied to EVERY row. `name` is the column label in the markdown report. */
+    readonly scorers: ReadonlyArray<{
+        readonly name: string;
+        readonly score: Scorer;
+    }>;
+    /** Options for the agent under test — one agent config for the whole suite. */
+    readonly agent: EvalAgentOptions;
+    /**
+     * Rows evaluated in parallel. Omitted means the key is not forwarded at all, so the SDK's own
+     * default applies. Raise it and you raise your provider rate-limit exposure with it.
+     */
+    readonly concurrency?: number;
+}
+
 /**
  * Top-level CLI dispatcher via commander (ADR D194).
  *
- * Subcommands: `init`, `dev`, `inspect`, `eval`, `setup`, `acp`, `tasks`.
+ * Subcommands: `init`, `dev`, `inspect`, `eval`, `acp`, `setup`, `db`, `tasks`.
  *
- * Exit codes:
- *  - 0  → success
- *  - 1  → unknown error
- *  - 2  → user error (bad flags, unknown subcommand suggestion)
+ * Exit codes at this layer:
+ *  - 0  → success, and also `--help` / `--version`
+ *  - 1  → unknown error (an exception that escaped a subcommand)
+ *  - 2  → user error (unknown subcommand, unknown option, bad flag value)
+ *
+ * Subcommands are free to return codes of their own beyond these — `theokit tasks` uses 3 and 4,
+ * `theokit db check-schema-drift` uses 1 to mean "drift found", and `theokit dev` forwards the
+ * child process's exit code verbatim. Each command module documents its own.
  *
  * @internal
  */
+/**
+ * Parse `argv` and run the matching subcommand, returning the process exit code instead of exiting.
+ *
+ * `argv` is commander-shaped, i.e. the full `process.argv`: `[execPath, scriptPath, ...args]`. The
+ * first two entries are skipped, so passing `["theokit", "init"]` silently drops `init` — pass
+ * `["node", "theokit", "init"]` when synthesising one.
+ *
+ * Never throws and never calls `process.exit`; the caller decides what to do with the code (the
+ * bundled `bin/theokit.ts` shim exits with it). Writes to `process.stdout` and `process.stderr`
+ * directly, so redirect the streams if you need to capture the output.
+ *
+ * Returns `0` for success and for `--help` / `--version`, `2` for a user error, `1` for anything
+ * that escaped a subcommand as an exception, and otherwise whatever the subcommand returned.
+ */
 declare function main(argv: ReadonlyArray<string>): Promise<number>;
 
 /**
  * Build-time version constants for @theokit/cli.
  *
- * `__SDK_VERSION__` is the sibling `@theokit/sdk` semver (NEVER
- * `workspace:*` — resolved at build time via tsup `define`). Used by
- * `init` templates to pin the SDK dep in scaffolded projects (EC-L
- * fix from edge-case review).
+ * Both are substituted by tsup `define` at BUILD time, so they are plain string literals in the
+ * shipped bundle. The `declare const` below only satisfies the type checker: evaluating this module
+ * from unbuilt source, without that substitution, throws a ReferenceError at import.
+ *
+ * `__SDK_VERSION__` is the sibling `@theokit/sdk` semver (NEVER `workspace:*`). Used by `init`
+ * templates to pin the SDK dep in scaffolded projects (EC-L fix from edge-case review).
  *
  * `__CLI_VERSION__` is this package's semver. Exposed via `--version`.
  */
+/**
+ * The `@theokit/sdk` semver this CLI was BUILT against — a concrete version, never `workspace:*`.
+ *
+ * `theokit init` writes it into the scaffolded `package.json`, so it is what a new project pins. It
+ * is not a claim about the SDK the current process has loaded, which may be a different version
+ * entirely.
+ */
 declare const SDK_VERSION: string;
+/**
+ * This package's semver, substituted at build time — what `theokit --version` prints.
+ *
+ * Distinct from {@link SDK_VERSION}, which is the `@theokit/sdk` version this CLI was built against
+ * and the one `theokit init` writes into a scaffolded `package.json`. They move independently, so a
+ * bug report should quote both.
+ */
 declare const CLI_VERSION: string;
 
-export { CLI_VERSION, SDK_VERSION, main };
+export { CLI_VERSION, type DatasetEntry, type EvalConfig, SDK_VERSION, type Score, type Scorer, main };

package/dist/index.js

@@ -358,7 +358,7 @@ function startRunner(opts) {
   args.push(opts.entry);
   const child = spawn(process.execPath, [tsxBin, ...args], {
     cwd: opts.cwd,
-    stdio: "inherit",
+    stdio: opts.stdio ?? "inherit",
     env: process.env
   });
   const exited = new Promise((resolve6) => {
@@ -489,7 +489,13 @@ function formatReport(result) {
 }
 function truncate(s, max) {
   if (s.length <= max) return s;
-  return `${s.slice(0, max - 1)}\u2026`;
+  const budget = max - 1;
+  let out = "";
+  for (const ch of s) {
+    if (out.length + ch.length > budget) break;
+    out += ch;
+  }
+  return `${out}\u2026`;
 }
 function escapeMd(s) {
   return s.replaceAll("|", "\\|").replaceAll("\n", " ");
@@ -619,8 +625,8 @@ ${pc5.green("\u2713")} ${result.aggregate.totalRows} rows \xB7 mean score ${resu
 }
 
 // src/version.ts
-var SDK_VERSION = "4.43.0";
-var CLI_VERSION = "3.0.2";
+var SDK_VERSION = "4.57.0";
+var CLI_VERSION = "4.0.1";
 
 // src/init/templates.ts
 var TEMPLATES = [
@@ -634,6 +640,26 @@ var TEMPLATES = [
     description: "100% local agent via Ollama (no remote API key required).",
     hint: "Requires `ollama serve` + `ollama pull llama3.2:3b`."
   },
+  {
+    name: "chatbot",
+    description: "Conversational agent that resumes its own thread across runs.",
+    hint: "SESSION_DIR=~/.claude writes sessions the Claude Code CLI can --continue."
+  },
+  {
+    name: "multi-agent",
+    description: "A classifier routes to specialists, all from one AgentFactory prefix.",
+    hint: 'Pass the input as an argument: `pnpm dev "Translate to French: hello"`.'
+  },
+  {
+    name: "rag-agent",
+    description: "Retrieval over your own files \u2014 Memory.openIndex behind a Tool.",
+    hint: "Put markdown under .theokit/memory/ first, or there is nothing to cite."
+  },
+  {
+    name: "workflow-automation",
+    description: "A committed Workflow (fn -> agentStep -> fn) handed to Cron.",
+    hint: "WORKFLOW_CRON overrides the schedule; default is every 5 minutes."
+  },
   {
     name: "telegram-bot",
     description: "Telegram bot via @theokit/gateway + grammy.",
@@ -695,6 +721,13 @@ function resolveTemplatesRoot() {
     `Could not locate bundled templates/ directory (searched up from ${here}). This usually means the published tarball was built without "files": ["templates"] (EC-C regression).`
   );
 }
+var SCAFFOLD_USER_ERROR_CODES = [
+  "invalid_project_name",
+  "unknown_template",
+  "invalid_dest",
+  "dest_is_symlink",
+  "dest_not_empty"
+];
 function scaffoldError(code, message) {
   const err = new Error(message);
   err.code = code;
@@ -830,12 +863,7 @@ async function resolveTemplate(optsTemplate, skipPrompts) {
   }
   return template;
 }
-var USER_ERROR_CODES = /* @__PURE__ */ new Set([
-  "invalid_project_name",
-  "dest_not_empty",
-  "invalid_dest",
-  "unknown_template"
-]);
+var USER_ERROR_CODES = new Set(SCAFFOLD_USER_ERROR_CODES);
 async function runScaffold(name, template, force) {
   try {
     const result = await scaffold({
@@ -1189,14 +1217,6 @@ ${pc5.dim("  shape: Desktop OAuth client (installed block present)")}
   }
   const interactiveCode = await runInteractiveSetup();
   if (interactiveCode !== 0) return interactiveCode;
-  if (typeof opts.writable === "string" && opts.writable.length > 0) {
-    process.stdout.write(
-      `
-${pc5.yellow("note:")} you passed --writable=${opts.writable}. The upstream MCP server does not narrow scopes \u2014 all scopes are granted at consent.
-Write tools are gated at runtime by ${pc5.bold("googleWorkspace({ writable: true })")} in your code.
-`
-    );
-  }
   process.stdout.write(
     `
 ${pc5.green("\u2713")} gworkspace setup complete.
@@ -1243,7 +1263,6 @@ function spawnUpstream(args, timeoutMs) {
 async function runSetup(domain, opts) {
   if (domain === "gworkspace") {
     const gworkspaceOpts = {
-      writable: opts.writable,
       probe: opts.probe === true,
       nonInteractive: opts.nonInteractive === true,
       ...opts.credentialsPath !== void 0 ? { credentialsPath: opts.credentialsPath } : {}
@@ -1374,7 +1393,7 @@ async function runTasksInspect(id, opts) {
   }
   return 0;
 }
-async function runTasksCancel(id, _opts) {
+async function runTasksCancel(id, opts) {
   if (!isValidTaskId(id)) {
     process.stderr.write(`tasks: invalid id grammar: ${id}
 `);
@@ -1399,12 +1418,21 @@ async function runTasksCancel(id, _opts) {
   }
   if (handle.state === "queued") {
     const cancelledAt = Date.now();
-    await store.update(id, (h) => ({ ...h, state: "cancelled", cancelledAt }));
+    await store.update(id, (h) => ({
+      ...h,
+      state: "cancelled",
+      cancelledAt,
+      ...opts.reason !== void 0 ? { cancelReason: opts.reason } : {}
+    }));
     process.stdout.write(`task ${id} cancelled (was queued)
 `);
     return 0;
   }
-  await store.update(id, (h) => ({ ...h, cancelRequested: true }));
+  await store.update(id, (h) => ({
+    ...h,
+    cancelRequested: true,
+    ...opts.reason !== void 0 ? { cancelReason: opts.reason } : {}
+  }));
   process.stdout.write(
     `cancel requested for task ${id}; the owning process will honor it at the next checkpoint
 `
@@ -1414,7 +1442,13 @@ async function runTasksCancel(id, _opts) {
 
 // src/main.ts
 function registerSubcommands(program, setExit) {
-  program.command("init [project-name]").description("Scaffold a new agent project from a bundled template.").option("-t, --template <name>", "Template name: minimal | ollama-local | telegram-bot").option("-f, --force", "Overwrite a non-empty destination directory").option("--here", "Scaffold into the current directory").option("-y, --yes", "Skip interactive prompts (CI mode)").action(async (projectName, opts) => {
+  program.command("init [project-name]").description("Scaffold a new agent project from a bundled template.").option(
+    "-t, --template <name>",
+    // Derived from the registry, not restated. This line named three templates while the
+    // registry held seven — a help text that lists options is a second copy of the list, and
+    // the copy is the one that goes stale.
+    `Template name: ${TEMPLATES.map((t) => t.name).join(" | ")}`
+  ).option("-f, --force", "Overwrite a non-empty destination directory").option("-y, --yes", "Skip interactive prompts (CI mode)").action(async (projectName, opts) => {
     setExit(await runInit(projectName, opts));
   });
   program.command("dev").description("Run the agent entry point under tsx --watch (hot-reload).").option("--entry <path>", "Entry file (default: src/index.ts or package.main)").option("--env <path>", "Env file to load (default: .env)").action(async (opts) => {
@@ -1430,15 +1464,12 @@ function registerSubcommands(program, setExit) {
     setExit(await runEval(opts));
   });
   program.command("acp").description(
-    "Launch a stdio Agent Client Protocol (ACP) server pointing at the entry file's default-exported agent. Used by Zed/Cursor/Claude Desktop. ADRs D349-D360."
+    "Launch a stdio Agent Client Protocol (ACP) server pointing at the entry file's default-exported agent. Used by ACP-compatible hosts. ADRs D349-D360."
   ).option("--entry <path>", "Entry file (default: src/index.ts or package.main)").option("--permission <mode>", "Tool permission mode: ask | auto | deny (default: ask)").option("--trusted-tools <list>", "Comma-separated tool names that bypass ask").option("--permission-timeout-ms <ms>", "Permission request timeout in ms (default: 60000)").action(async (opts) => {
     setExit(await runAcp(opts));
   });
   program.command("setup <domain>").description(
     "Stage credentials + connectivity probe for a third-party integration. Domains: gworkspace (Google Workspace)."
-  ).option(
-    "--writable <products>",
-    "Comma-separated products to grant write access (e.g., 'drive,calendar')"
   ).option("--probe", "Run upstream connectivity check after staging credentials").option(
     "--credentials-path <path>",
     "Override path to credentials.json (default: ~/.google-mcp/credentials.json)"
@@ -1476,7 +1507,7 @@ function registerSubcommands(program, setExit) {
     setExit(await runTasksInspect(id, opts));
   });
   tasks.command("cancel <id>").description("Cancel a task (best-effort cross-process via cancelRequested flag)").option("--reason <reason>", "Cancellation reason recorded in the registry").action(async (id, opts) => {
-    setExit(await runTasksCancel(id));
+    setExit(await runTasksCancel(id, opts));
   });
 }
 function mapCommanderExitCode(code, fallback) {