@hasna/todos 0.15.20 → 0.15.24

package/dist/contracts.js

@@ -4731,7 +4731,7 @@ var init_database = __esm(() => {
 });
 
 // src/lib/config.ts
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
 import { dirname as dirname2, join as join3 } from "path";
 function getConfigPath() {
   return join3(getTodosGlobalDir(), "config.json");
@@ -4763,6 +4763,22 @@ function saveConfig(config) {
 function updateConfig(patch) {
   return saveConfig({ ...loadConfig(), ...patch });
 }
+function getTodosAiConfig() {
+  const configPath = getConfigPath();
+  if (!existsSync4(configPath))
+    return {};
+  const parsed = JSON.parse(readFileSync2(configPath, "utf8"));
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Todos config must be a JSON object");
+  }
+  const ai = parsed["ai"];
+  if (ai === undefined)
+    return {};
+  if (ai === null || typeof ai !== "object" || Array.isArray(ai)) {
+    throw new Error("Todos AI configuration must be an object");
+  }
+  return { ...ai };
+}
 function normalizeApiUrl(value) {
   const trimmed = value?.trim();
   if (!trimmed)
@@ -7093,7 +7109,7 @@ var init_shared_events = __esm(() => {
 });
 
 // src/lib/secret-redaction.ts
-import { readFileSync as readFileSync2, existsSync as existsSync6 } from "fs";
+import { readFileSync as readFileSync3, existsSync as existsSync6 } from "fs";
 function registerCustomRedactor(fn) {
   customRedactors.push(fn);
 }
@@ -7160,7 +7176,7 @@ function scanAndRedactText(text, options = {}) {
 function scanFileForSecrets(path, options = {}) {
   if (!existsSync6(path))
     throw new Error(`File not found: ${path}`);
-  const content = readFileSync2(path, "utf8");
+  const content = readFileSync3(path, "utf8");
   return scanAndRedactText(content, options);
 }
 function safeStringify(value, space) {
@@ -8606,7 +8622,7 @@ function requireCanonicalLockVersion(value) {
     throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", "expected_lock_version must be the exact canonical locked_at timestamp (YYYY-MM-DDTHH:mm:ss.sssZ)", { field: "expected_lock_version" });
   }
   const parsed = Date.parse(value);
-  if (Number.isNaN(parsed) || new Date(parsed).toISOString() !== value) {
+  if (value.startsWith("0000-") || Number.isNaN(parsed) || new Date(parsed).toISOString() !== value) {
     throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", "expected_lock_version must name a real canonical UTC instant", { field: "expected_lock_version" });
   }
   return value;
@@ -8631,9 +8647,6 @@ function prepareStaleLockHandoff(input, options = {}) {
   if (canonicalAgentRef(actor) !== canonicalAgentRef(newHolder)) {
     throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_ACTOR_MISMATCH", "new_holder must match the authenticated actor", { actor, new_holder: newHolder });
   }
-  if (canonicalAgentRef(expectedHolder) === canonicalAgentRef(newHolder)) {
-    throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", "new_holder must differ from expected_holder", { field: "new_holder" });
-  }
   const operationTimestamp = options.now ?? new Date().toISOString();
   if (!CANONICAL_LOCK_VERSION_RE.test(operationTimestamp) || new Date(Date.parse(operationTimestamp)).toISOString() !== operationTimestamp) {
     throw new StaleLockHandoffError("STALE_LOCK_HANDOFF_INVALID_INPUT", "operation timestamp must be a canonical UTC instant");
@@ -11211,7 +11224,7 @@ var init_boards = __esm(() => {
 
 // src/lib/artifact-store.ts
 import { createHash as createHash3 } from "crypto";
-import { existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync3, rmSync, statSync as statSync2, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync4, rmSync, statSync as statSync2, writeFileSync as writeFileSync2 } from "fs";
 import { basename, dirname as dirname4, join as join5, resolve as resolve7 } from "path";
 import { tmpdir as tmpdir2 } from "os";
 function isInMemoryDb2(path) {
@@ -11278,7 +11291,7 @@ function storeArtifactContent(input) {
   const sourceStat = statSync2(sourcePath);
   if (!sourceStat.isFile())
     throw new Error(`Artifact path is not a file: ${sanitizePreWriteText(input.path, "artifact.path")}`);
-  const sourceBuffer = readFileSync3(sourcePath);
+  const sourceBuffer = readFileSync4(sourcePath);
   const sourceSha = sha256(sourceBuffer);
   const textLike = isTextLike(sourceBuffer, input.path);
   let storedBuffer = sourceBuffer;
@@ -11365,7 +11378,7 @@ function verifyStoredArtifact(input) {
       message: "stored artifact content is missing"
     };
   }
-  const buffer = readFileSync3(storedPath);
+  const buffer = readFileSync4(storedPath);
   const actualSha = sha256(buffer);
   const actualSize = buffer.length;
   const ok = actualSha === store.sha256 && actualSize === store.size_bytes;
@@ -11385,7 +11398,7 @@ function exportStoredArtifactContent(input) {
   const report = verifyStoredArtifact(input);
   if (report.status !== "ok" || !report.relative_path || !report.actual_sha256 || report.actual_size_bytes === null)
     return null;
-  const content = readFileSync3(artifactStorePath(report.relative_path));
+  const content = readFileSync4(artifactStorePath(report.relative_path));
   return {
     artifact_id: input.id,
     sha256: report.actual_sha256,
@@ -11436,7 +11449,7 @@ function getArtifactStoreRoot(dbPath) {
   return join5(dirname4(resolve7(path)), "artifacts");
 }
 function computeContentHash(path) {
-  return sha256(readFileSync3(resolve7(path)));
+  return sha256(readFileSync4(resolve7(path)));
 }
 function storeArtifactFile(input) {
   const sourcePath = resolve7(input.sourcePath);
@@ -11446,7 +11459,7 @@ function storeArtifactFile(input) {
   if (!statSync2(sourcePath).isFile()) {
     throw new Error(`Source path is not a file: ${input.sourcePath}`);
   }
-  const buffer = readFileSync3(sourcePath);
+  const buffer = readFileSync4(sourcePath);
   const contentHash = sha256(buffer);
   const mimeType = mediaTypeFor(sourcePath, isTextLike(buffer, sourcePath));
   const storageMode = input.storageMode ?? "copy";
@@ -12645,7 +12658,7 @@ var init_tasks = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/todos",
-  version: "0.15.20",
+  version: "0.15.24",
   description: "Universal task management for AI coding agents - CLI + MCP server + interactive TUI",
   type: "module",
   main: "dist/index.js",
@@ -15416,6 +15429,578 @@ function createJsonContractsManifest(options = {}) {
 var TODOS_JSON_CONTRACTS_MANIFEST = createJsonContractsManifest({
   generatedAt: "1970-01-01T00:00:00.000Z"
 });
+
+// src/ai.ts
+var TODOS_AI_SCHEMA_VERSION = 1;
+var TODOS_AI_RUNTIME_PROTOCOL_VERSION = 1;
+var TODOS_AI_RUNTIME_SPECIFIER = "@hasna/todos-ai/runtime";
+var TODOS_AI_UPDATE_TASK_RESULT_SCHEMA = "todos.ai.update_task.v1";
+var TODOS_AI_FORMATS = ["text", "json", "stream-json"];
+var TODOS_AI_WRITE_MODES = ["read-only", "plan", "execute"];
+var TODOS_AI_APPROVAL_MODES = ["deny", "required", "prompt", "existing"];
+var TODOS_AI_RUN_STATUSES = [
+  "answered",
+  "needs_input",
+  "needs_approval",
+  "completed",
+  "failed"
+];
+var TODOS_AI_RUNTIME_EVENT_TYPES = [
+  "run.started",
+  "run.progress",
+  "text.delta",
+  "tool.started",
+  "tool.completed",
+  "input.required",
+  "approval.required"
+];
+var TODOS_AI_TOOL_EFFECTS = ["read", "control", "write"];
+var TODOS_AI_UPDATE_TASK_FIELDS = [
+  "title",
+  "description",
+  "status",
+  "priority",
+  "assigned_to",
+  "tags",
+  "due_at"
+];
+var TODOS_AI_UPDATE_TASK_LIMITS = {
+  max_title_bytes: 1024,
+  max_description_bytes: 8192,
+  max_assignee_bytes: 256,
+  max_tags: 16,
+  max_tag_bytes: 128,
+  max_due_at_bytes: 128,
+  min_idempotency_key_bytes: 8,
+  max_idempotency_key_bytes: 128,
+  max_result_bytes: 65536
+};
+var TODOS_AI_DEFAULTS = {
+  format: "text",
+  max_steps: 8,
+  timeout_ms: 60000,
+  write_mode: "read-only"
+};
+var TODOS_AI_LIMITS = {
+  max_prompt_bytes: 1048576,
+  max_json_bytes: 1048576,
+  max_result_bytes: 4194304,
+  max_variable_count: 100,
+  max_variable_value_bytes: 65536,
+  max_approval_refs: 32,
+  max_approval_ref_bytes: 1024,
+  max_resume_run_id_bytes: 1024,
+  max_pending_input_prompt_bytes: 1024,
+  max_pending_input_fields: 16,
+  max_pending_input_field_bytes: 128,
+  max_pending_approval_id_bytes: 256,
+  max_pending_approval_summary_bytes: 1024,
+  max_pending_approval_operations: 4,
+  max_pending_approval_bytes: 8192,
+  max_stream_events: 1000,
+  max_stream_record_bytes: 262144,
+  max_stream_bytes: 8388608,
+  min_steps: 1,
+  max_steps: 20,
+  min_timeout_ms: 1000,
+  max_timeout_ms: 600000
+};
+var TODOS_AI_EXIT_CODES = {
+  success: 0,
+  usage: 2,
+  needs_input: 3,
+  needs_approval: 4,
+  runtime_unavailable: 5,
+  failed: 6,
+  timeout: 124,
+  interrupted: 130
+};
+var TODOS_AI_PROTOCOL = {
+  schema_version: TODOS_AI_SCHEMA_VERSION,
+  runtime_protocol_version: TODOS_AI_RUNTIME_PROTOCOL_VERSION,
+  runtime_specifier: TODOS_AI_RUNTIME_SPECIFIER,
+  formats: TODOS_AI_FORMATS,
+  write_modes: TODOS_AI_WRITE_MODES,
+  approval_modes: TODOS_AI_APPROVAL_MODES,
+  statuses: TODOS_AI_RUN_STATUSES,
+  event_types: TODOS_AI_RUNTIME_EVENT_TYPES,
+  tool_effects: TODOS_AI_TOOL_EFFECTS,
+  defaults: TODOS_AI_DEFAULTS,
+  limits: TODOS_AI_LIMITS,
+  exit_codes: TODOS_AI_EXIT_CODES
+};
+
+class TodosAiContractError extends Error {
+  code;
+  exitCode;
+  constructor(code, message, exitCode = TODOS_AI_EXIT_CODES.usage, options) {
+    super(message, options);
+    this.code = code;
+    this.exitCode = exitCode;
+    this.name = "TodosAiContractError";
+  }
+}
+
+class TodosAiNeedsInputSignal extends Error {
+  pending_input;
+  constructor(pendingInput) {
+    if (!isTodosAiJsonValue(pendingInput) || !isPendingInput(pendingInput)) {
+      throw new TodosAiContractError("invalid_input", "Todos AI pending input must be bounded stable control data");
+    }
+    super("Todos AI input required");
+    this.name = "TodosAiNeedsInputSignal";
+    this.pending_input = {
+      prompt: pendingInput.prompt,
+      fields: [...pendingInput.fields]
+    };
+  }
+}
+
+class TodosAiNeedsApprovalSignal extends Error {
+  pending_approval;
+  constructor(pendingApproval) {
+    if (!isTodosAiJsonValue(pendingApproval) || !isPendingApproval(pendingApproval)) {
+      throw new TodosAiContractError("invalid_input", "Todos AI pending approval must be bounded stable control data");
+    }
+    super("Todos AI approval required");
+    this.name = "TodosAiNeedsApprovalSignal";
+    this.pending_approval = {
+      id: pendingApproval.id,
+      summary: pendingApproval.summary,
+      operations: pendingApproval.operations.map((operation) => JSON.parse(JSON.stringify(operation)))
+    };
+  }
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isJsonObject(value) {
+  if (!isRecord(value))
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function prototypeDefinesToJson(value) {
+  let prototype = Object.getPrototypeOf(value);
+  while (prototype !== null) {
+    if (Object.getOwnPropertyDescriptor(prototype, "toJSON") !== undefined)
+      return true;
+    prototype = Object.getPrototypeOf(prototype);
+  }
+  return false;
+}
+function isStableJsonArray(value, ancestors, depth) {
+  if (Object.getPrototypeOf(value) !== Array.prototype || prototypeDefinesToJson(value)) {
+    return false;
+  }
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== value.length + 1)
+    return false;
+  for (const key of keys) {
+    if (key === "length")
+      continue;
+    if (typeof key !== "string" || !/^(0|[1-9]\d*)$/.test(key))
+      return false;
+    const index = Number(key);
+    if (!Number.isSafeInteger(index) || index < 0 || index >= value.length)
+      return false;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+      return false;
+    if (!isTodosAiJsonValueInternal(descriptor.value, ancestors, depth + 1))
+      return false;
+  }
+  return true;
+}
+function isStableJsonObject(value, ancestors, depth) {
+  if (!isJsonObject(value) || prototypeDefinesToJson(value))
+    return false;
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string")
+      return false;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+      return false;
+    if (!isTodosAiJsonValueInternal(descriptor.value, ancestors, depth + 1))
+      return false;
+  }
+  return true;
+}
+function isOneOf(value, values) {
+  return typeof value === "string" && values.includes(value);
+}
+function selectedString(...values) {
+  for (const value of values) {
+    if (value === undefined || value === null)
+      continue;
+    const trimmed = value.trim();
+    if (trimmed)
+      return trimmed;
+  }
+  return null;
+}
+function parseEnum(value, values, field2, fallback) {
+  if (value === null)
+    return fallback;
+  if (isOneOf(value, values))
+    return value;
+  throw new TodosAiContractError("invalid_configuration", `${field2} must be one of: ${values.join(", ")}`);
+}
+function parseBoundedInteger(value, field2, fallback, min, max) {
+  if (value === undefined || value === null || value === "")
+    return fallback;
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+    throw new TodosAiContractError("invalid_configuration", `${field2} must be an integer between ${min} and ${max}`);
+  }
+  return parsed;
+}
+function normalizeApprovalRefs(values) {
+  const refs = [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
+  if (refs.length > TODOS_AI_LIMITS.max_approval_refs) {
+    throw new TodosAiContractError("invalid_configuration", `--approval may be repeated at most ${TODOS_AI_LIMITS.max_approval_refs} times`);
+  }
+  for (const ref of refs) {
+    if (new TextEncoder().encode(ref).byteLength > TODOS_AI_LIMITS.max_approval_ref_bytes) {
+      throw new TodosAiContractError("invalid_configuration", `--approval references may not exceed ${TODOS_AI_LIMITS.max_approval_ref_bytes} bytes`);
+    }
+  }
+  return refs;
+}
+function resolveTodosAiCommandOptions(input) {
+  const cli = input.cli ?? {};
+  const config = input.config ?? {};
+  const env = input.env ?? {};
+  const format = parseEnum(selectedString(cli.format, env["TODOS_AI_FORMAT"], config.format), TODOS_AI_FORMATS, "format", TODOS_AI_DEFAULTS.format);
+  const configuredWriteMode = parseEnum(selectedString(cli.writeMode, env["TODOS_AI_WRITE_MODE"], config.write_mode), TODOS_AI_WRITE_MODES, "write mode", TODOS_AI_DEFAULTS.write_mode);
+  if (cli.dryRun && cli.writeMode === "execute") {
+    throw new TodosAiContractError("invalid_configuration", "--dry-run cannot be combined with --write-mode execute");
+  }
+  const writeMode = cli.dryRun ? "plan" : configuredWriteMode;
+  const explicitApproval = cli.dryRun ? selectedString(cli.approvalMode) : selectedString(cli.approvalMode, env["TODOS_AI_APPROVAL_MODE"], config.approval_mode);
+  const defaultApproval = writeMode === "execute" ? input.interactive ? "prompt" : "required" : "deny";
+  const approvalMode = cli.dryRun ? parseEnum(explicitApproval, TODOS_AI_APPROVAL_MODES, "approval mode", "deny") : parseEnum(explicitApproval, TODOS_AI_APPROVAL_MODES, "approval mode", defaultApproval);
+  const approvalRefs = normalizeApprovalRefs(cli.approvalRefs);
+  if (cli.dryRun && approvalMode !== "deny") {
+    throw new TodosAiContractError("invalid_configuration", "--dry-run requires approval mode deny");
+  }
+  if (writeMode !== "execute" && approvalMode !== "deny") {
+    throw new TodosAiContractError("invalid_configuration", "approval modes other than deny require --write-mode execute");
+  }
+  if (writeMode === "execute" && approvalMode === "deny") {
+    throw new TodosAiContractError("invalid_configuration", "--write-mode execute requires approval mode required, prompt, or existing");
+  }
+  if (!input.interactive && approvalMode === "prompt") {
+    throw new TodosAiContractError("invalid_configuration", "approval mode prompt is unavailable in non-interactive mode");
+  }
+  if (approvalMode === "existing" && approvalRefs.length === 0) {
+    throw new TodosAiContractError("invalid_configuration", "approval mode existing requires at least one --approval reference");
+  }
+  if (approvalMode !== "existing" && approvalRefs.length > 0) {
+    throw new TodosAiContractError("invalid_configuration", "--approval references require --approval-mode existing");
+  }
+  return {
+    provider: selectedString(cli.provider, env["TODOS_AI_PROVIDER"], config.provider),
+    model: selectedString(cli.model, env["TODOS_AI_MODEL"], config.model),
+    profile: selectedString(cli.profile, env["TODOS_AI_PROFILE"], config.profile),
+    format,
+    max_steps: parseBoundedInteger(cli.maxSteps ?? env["TODOS_AI_MAX_STEPS"] ?? config.max_steps, "max steps", TODOS_AI_DEFAULTS.max_steps, TODOS_AI_LIMITS.min_steps, TODOS_AI_LIMITS.max_steps),
+    timeout_ms: parseBoundedInteger(cli.timeoutMs ?? env["TODOS_AI_TIMEOUT_MS"] ?? config.timeout_ms, "timeout", TODOS_AI_DEFAULTS.timeout_ms, TODOS_AI_LIMITS.min_timeout_ms, TODOS_AI_LIMITS.max_timeout_ms),
+    write_mode: writeMode,
+    approval_mode: approvalMode,
+    approval_refs: approvalRefs,
+    dry_run: cli.dryRun === true,
+    interactive: input.interactive
+  };
+}
+function normalizeTodosAiPrompt(value) {
+  const prompt = value.trim();
+  if (new TextEncoder().encode(prompt).byteLength > TODOS_AI_LIMITS.max_prompt_bytes) {
+    throw new TodosAiContractError("invalid_input", `prompt exceeds ${TODOS_AI_LIMITS.max_prompt_bytes} bytes`);
+  }
+  return prompt;
+}
+function parseTodosAiJson(value, field2) {
+  if (new TextEncoder().encode(value).byteLength > TODOS_AI_LIMITS.max_json_bytes) {
+    throw new TodosAiContractError("invalid_input", `${field2} exceeds ${TODOS_AI_LIMITS.max_json_bytes} bytes`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new TodosAiContractError("invalid_input", `${field2} must be valid JSON: ${detail}`);
+  }
+  if (!isTodosAiJsonValue(parsed)) {
+    throw new TodosAiContractError("invalid_input", `${field2} must contain only stable JSON values`);
+  }
+  return parsed;
+}
+function parseTodosAiOutputSchema(value) {
+  const parsed = parseTodosAiJson(value, "output schema");
+  if (!isRecord(parsed)) {
+    throw new TodosAiContractError("invalid_input", "output schema must be a JSON object");
+  }
+  return parsed;
+}
+var SENSITIVE_VARIABLE_KEY = /(?:^|[_.-])(api[_-]?key|credential|password|secret|token)(?:$|[_.-])/i;
+function parseTodosAiVariables(values) {
+  if (values.length > TODOS_AI_LIMITS.max_variable_count) {
+    throw new TodosAiContractError("invalid_input", `--var may be repeated at most ${TODOS_AI_LIMITS.max_variable_count} times`);
+  }
+  const variables = Object.create(null);
+  for (const entry of values) {
+    const separator = entry.indexOf("=");
+    const key = separator >= 0 ? entry.slice(0, separator).trim() : "";
+    const value = separator >= 0 ? entry.slice(separator + 1) : "";
+    if (!/^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/.test(key)) {
+      throw new TodosAiContractError("invalid_input", `invalid --var entry ${JSON.stringify(entry)}; expected non-secret key=value`);
+    }
+    if (SENSITIVE_VARIABLE_KEY.test(key)) {
+      throw new TodosAiContractError("invalid_input", `--var ${key} is credential-shaped; provide credentials through the runtime's secret configuration`);
+    }
+    if (Object.hasOwn(variables, key)) {
+      throw new TodosAiContractError("invalid_input", `duplicate --var key: ${key}`);
+    }
+    if (new TextEncoder().encode(value).byteLength > TODOS_AI_LIMITS.max_variable_value_bytes) {
+      throw new TodosAiContractError("invalid_input", `--var ${key} exceeds ${TODOS_AI_LIMITS.max_variable_value_bytes} bytes`);
+    }
+    variables[key] = value;
+  }
+  return variables;
+}
+function isTodosAiJsonValue(value) {
+  return isTodosAiJsonValueInternal(value, new Set, 0);
+}
+function isTodosAiUpdateTaskResult(value) {
+  if (!isTodosAiJsonValue(value) || !isRecord(value) || !hasOnlyKeys(value, [
+    "schema",
+    "operation",
+    "mode",
+    "applied",
+    "readback_verified",
+    "source",
+    "target",
+    "changed_fields",
+    "approval_ref",
+    "payload_digest",
+    "idempotency"
+  ]) || value["schema"] !== TODOS_AI_UPDATE_TASK_RESULT_SCHEMA || value["operation"] !== "update_task" || value["mode"] !== "plan" && value["mode"] !== "execute" || value["source"] !== "sqlite" && value["source"] !== "http") {
+    return false;
+  }
+  const changedFields = value["changed_fields"];
+  const target = value["target"];
+  const idempotency = value["idempotency"];
+  const payloadDigest = value["payload_digest"];
+  const approvalRef = value["approval_ref"];
+  if (!Array.isArray(changedFields) || changedFields.length === 0 || changedFields.length > TODOS_AI_UPDATE_TASK_FIELDS.length || !changedFields.every((field2) => typeof field2 === "string" && TODOS_AI_UPDATE_TASK_FIELDS.includes(field2)) || new Set(changedFields).size !== changedFields.length || !TODOS_AI_UPDATE_TASK_FIELDS.filter((field2) => changedFields.includes(field2)).every((field2, index) => changedFields[index] === field2) || !isRecord(target) || !hasOnlyKeys(target, ["task_id", "expected_version", "result_version"]) || typeof target["task_id"] !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(target["task_id"]) || !Number.isSafeInteger(target["expected_version"]) || target["expected_version"] < 0 || typeof payloadDigest !== "string" || !/^[0-9a-f]{64}$/.test(payloadDigest) || approvalRef !== `todos-ai:update_task:${payloadDigest}` || !isRecord(idempotency) || !hasOnlyKeys(idempotency, ["key", "scope", "replay"]) || !boundedUtf8String(idempotency["key"], TODOS_AI_UPDATE_TASK_LIMITS.max_idempotency_key_bytes) || new TextEncoder().encode(idempotency["key"]).byteLength < TODOS_AI_UPDATE_TASK_LIMITS.min_idempotency_key_bytes || !/^[A-Za-z0-9._:-]+$/.test(idempotency["key"]) || idempotency["scope"] !== "run" || typeof idempotency["replay"] !== "boolean" || new TextEncoder().encode(JSON.stringify(value)).byteLength > TODOS_AI_UPDATE_TASK_LIMITS.max_result_bytes) {
+    return false;
+  }
+  if (value["mode"] === "plan") {
+    return value["applied"] === false && value["readback_verified"] === false && target["result_version"] === null;
+  }
+  return value["applied"] === true && value["readback_verified"] === true && Number.isSafeInteger(target["result_version"]) && target["result_version"] === target["expected_version"] + 1;
+}
+function isTodosAiJsonValueInternal(value, ancestors, depth) {
+  if (depth > 64)
+    return false;
+  if (value === null || typeof value === "string" || typeof value === "boolean")
+    return true;
+  if (typeof value === "number")
+    return Number.isFinite(value);
+  if (typeof value !== "object")
+    return false;
+  if (ancestors.has(value))
+    return false;
+  ancestors.add(value);
+  try {
+    return Array.isArray(value) ? isStableJsonArray(value, ancestors, depth) : isStableJsonObject(value, ancestors, depth);
+  } catch {
+    return false;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+function isUsage(value) {
+  if (!isRecord(value))
+    return false;
+  return ["input_tokens", "output_tokens", "total_tokens"].every((key) => Number.isSafeInteger(value[key]) && value[key] >= 0);
+}
+function hasOnlyKeys(value, keys) {
+  const allowed = new Set(keys);
+  return Reflect.ownKeys(value).every((key) => typeof key === "string" && allowed.has(key));
+}
+function boundedUtf8String(value, maximum, allowEmpty = false) {
+  return typeof value === "string" && (allowEmpty || value.length > 0) && new TextEncoder().encode(value).byteLength <= maximum;
+}
+function isPendingInput(value) {
+  if (!isRecord(value) || !hasOnlyKeys(value, ["prompt", "fields"]))
+    return false;
+  if (!boundedUtf8String(value["prompt"], TODOS_AI_LIMITS.max_pending_input_prompt_bytes)) {
+    return false;
+  }
+  if (!Array.isArray(value["fields"]) || value["fields"].length === 0 || value["fields"].length > TODOS_AI_LIMITS.max_pending_input_fields) {
+    return false;
+  }
+  const fields = value["fields"];
+  const unique = new Set;
+  for (const field2 of fields) {
+    if (!boundedUtf8String(field2, TODOS_AI_LIMITS.max_pending_input_field_bytes) || !/^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/.test(field2) || unique.has(field2)) {
+      return false;
+    }
+    unique.add(field2);
+  }
+  return true;
+}
+function isPendingApproval(value) {
+  if (!isRecord(value) || !hasOnlyKeys(value, ["id", "summary", "operations"])) {
+    return false;
+  }
+  if (!boundedUtf8String(value["id"], TODOS_AI_LIMITS.max_pending_approval_id_bytes) || !boundedUtf8String(value["summary"], TODOS_AI_LIMITS.max_pending_approval_summary_bytes) || !Array.isArray(value["operations"]) || value["operations"].length === 0 || value["operations"].length > TODOS_AI_LIMITS.max_pending_approval_operations || !value["operations"].every(isRecord) || !value["operations"].every(isTodosAiJsonValue)) {
+    return false;
+  }
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength <= TODOS_AI_LIMITS.max_pending_approval_bytes;
+}
+function isAiError(value) {
+  if (!isRecord(value))
+    return false;
+  const code = value["code"];
+  const validCode = [
+    "invalid_input",
+    "invalid_configuration",
+    "runtime_unavailable",
+    "runtime_incompatible",
+    "runtime_invalid_result",
+    "needs_input",
+    "needs_approval",
+    "timeout",
+    "interrupted",
+    "provider_error",
+    "tool_error",
+    "schema_error",
+    "internal_error"
+  ];
+  return typeof code === "string" && validCode.includes(code) && typeof value["message"] === "string" && typeof value["retryable"] === "boolean" && (value["details"] === null || isRecord(value["details"]) && isTodosAiJsonValue(value["details"]));
+}
+function isTodosAiRunResult(value) {
+  if (!isRecord(value) || !isTodosAiJsonValue(value))
+    return false;
+  const structurallyValid = value["schema_version"] === TODOS_AI_SCHEMA_VERSION && typeof value["run_id"] === "string" && Boolean(value["run_id"]) && isOneOf(value["status"], TODOS_AI_RUN_STATUSES) && (value["answer"] === null || typeof value["answer"] === "string") && isTodosAiJsonValue(value["data"]) && Number.isSafeInteger(value["steps"]) && value["steps"] >= 0 && (value["usage"] === null || isUsage(value["usage"])) && (value["pending_input"] === null || isPendingInput(value["pending_input"])) && (value["pending_approval"] === null || isPendingApproval(value["pending_approval"])) && (value["error"] === null || isAiError(value["error"]));
+  if (!structurallyValid)
+    return false;
+  switch (value["status"]) {
+    case "answered":
+      return typeof value["answer"] === "string" && value["pending_input"] === null && value["pending_approval"] === null && value["error"] === null;
+    case "completed":
+      return isTodosAiUpdateTaskResult(value["data"]) && value["data"]["mode"] === "execute" && value["data"]["applied"] === true && value["data"]["readback_verified"] === true && value["pending_input"] === null && value["pending_approval"] === null && value["error"] === null;
+    case "needs_input":
+      return value["pending_input"] !== null && value["pending_approval"] === null && value["error"] === null;
+    case "needs_approval":
+      return value["pending_input"] === null && value["pending_approval"] !== null && value["error"] === null;
+    case "failed":
+      return value["pending_input"] === null && value["pending_approval"] === null && value["error"] !== null;
+  }
+  return false;
+}
+function assertTodosAiRunResult(value) {
+  if (!isTodosAiRunResult(value)) {
+    throw new TodosAiContractError("runtime_invalid_result", "optional AI runtime returned a result that does not satisfy the Todos AI protocol", TODOS_AI_EXIT_CODES.failed);
+  }
+  return value;
+}
+function isTodosAiRuntimeEvent(value) {
+  if (!isRecord(value) || !isTodosAiJsonValue(value))
+    return false;
+  return value["schema_version"] === TODOS_AI_SCHEMA_VERSION && typeof value["run_id"] === "string" && Boolean(value["run_id"]) && Number.isSafeInteger(value["sequence"]) && value["sequence"] >= 0 && isOneOf(value["type"], TODOS_AI_RUNTIME_EVENT_TYPES) && typeof value["timestamp"] === "string" && isRecord(value["data"]) && isTodosAiJsonValue(value["data"]);
+}
+function assertTodosAiRuntimeModule(value) {
+  if (!isRecord(value) || value["TODOS_AI_RUNTIME_PROTOCOL_VERSION"] !== TODOS_AI_RUNTIME_PROTOCOL_VERSION || typeof value["createTodosAiRuntime"] !== "function") {
+    throw new TodosAiContractError("runtime_incompatible", `optional AI runtime must implement protocol ${TODOS_AI_RUNTIME_PROTOCOL_VERSION}`, TODOS_AI_EXIT_CODES.runtime_unavailable);
+  }
+  return value;
+}
+function assertTodosAiRuntime(value) {
+  if (!isRecord(value) || typeof value["run"] !== "function") {
+    throw new TodosAiContractError("runtime_incompatible", `optional AI runtime must implement protocol ${TODOS_AI_RUNTIME_PROTOCOL_VERSION}`, TODOS_AI_EXIT_CODES.runtime_unavailable);
+  }
+  return value;
+}
+var defaultTodosAiRuntimeImporter = async (specifier) => import(specifier);
+async function loadTodosAiRuntime(context, importer = defaultTodosAiRuntimeImporter) {
+  let imported;
+  try {
+    imported = await importer(TODOS_AI_RUNTIME_SPECIFIER);
+  } catch (cause) {
+    throw new TodosAiContractError("runtime_unavailable", `optional AI runtime is unavailable; install a compatible ${TODOS_AI_RUNTIME_SPECIFIER}`, TODOS_AI_EXIT_CODES.runtime_unavailable, { cause });
+  }
+  const runtimeModule = assertTodosAiRuntimeModule(imported);
+  return assertTodosAiRuntime(await runtimeModule.createTodosAiRuntime(context));
+}
+function createTodosAiFailureResult(runId, code, message, retryable = false, details = null) {
+  return {
+    schema_version: TODOS_AI_SCHEMA_VERSION,
+    run_id: runId,
+    status: "failed",
+    answer: null,
+    data: null,
+    steps: 0,
+    usage: null,
+    pending_input: null,
+    pending_approval: null,
+    error: { code, message, retryable, details }
+  };
+}
+function createTodosAiNeedsInputResult(runId, message) {
+  return {
+    schema_version: TODOS_AI_SCHEMA_VERSION,
+    run_id: runId,
+    status: "needs_input",
+    answer: null,
+    data: null,
+    steps: 0,
+    usage: null,
+    pending_input: { prompt: message, fields: ["prompt"] },
+    pending_approval: null,
+    error: null
+  };
+}
+function createTodosAiNeedsApprovalResult(runId, pendingApproval) {
+  const signal = new TodosAiNeedsApprovalSignal(pendingApproval);
+  return {
+    schema_version: TODOS_AI_SCHEMA_VERSION,
+    run_id: runId,
+    status: "needs_approval",
+    answer: null,
+    data: null,
+    steps: 0,
+    usage: null,
+    pending_input: null,
+    pending_approval: signal.pending_approval,
+    error: null
+  };
+}
+function todosAiExitCodeForResult(result) {
+  if (result.status === "answered" || result.status === "completed")
+    return TODOS_AI_EXIT_CODES.success;
+  if (result.status === "needs_input")
+    return TODOS_AI_EXIT_CODES.needs_input;
+  if (result.status === "needs_approval")
+    return TODOS_AI_EXIT_CODES.needs_approval;
+  switch (result.error?.code) {
+    case "invalid_input":
+    case "invalid_configuration":
+      return TODOS_AI_EXIT_CODES.usage;
+    case "runtime_unavailable":
+    case "runtime_incompatible":
+      return TODOS_AI_EXIT_CODES.runtime_unavailable;
+    case "timeout":
+      return TODOS_AI_EXIT_CODES.timeout;
+    case "interrupted":
+      return TODOS_AI_EXIT_CODES.interrupted;
+    default:
+      return TODOS_AI_EXIT_CODES.failed;
+  }
+}
 // src/lib/onboarding-fixtures.ts
 import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync3 } from "fs";
 import { join as join6 } from "path";
@@ -16371,7 +16956,7 @@ function importOnboardingFixture(options = {}) {
 // src/lib/local-backups.ts
 init_database();
 import { createHash as createHash4 } from "crypto";
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "fs";
 import { dirname as dirname5, resolve as resolve8 } from "path";
 import { mkdirSync as mkdirSync6 } from "fs";
 var TODOS_LOCAL_BACKUP_KIND = "hasna.todos.local-backup";
@@ -16486,7 +17071,7 @@ function writeLocalBackupFile(backup, outputPath) {
   return path;
 }
 function readLocalBackupFile(path) {
-  return JSON.parse(readFileSync4(resolve8(path), "utf-8"));
+  return JSON.parse(readFileSync5(resolve8(path), "utf-8"));
 }
 function verifyLocalBackup(value, options = {}, db) {
   const verifiedAt = options.verified_at ?? now();
@@ -20433,7 +21018,7 @@ function renderLocalAuditLedgerMarkdown(ledger) {
 // src/lib/release-compatibility.ts
 init_migrations();
 init_schema();
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 import { join as join8, resolve as resolve9 } from "path";
 import { Database as Database2 } from "bun:sqlite";
 var LOCAL_RELEASE_COMPATIBILITY_SCHEMA_VERSION = 1;
@@ -20480,7 +21065,7 @@ function warn(id, message, details) {
   return { id, status: "warning", message, details };
 }
 function readPackageJson(root) {
-  return JSON.parse(readFileSync5(join8(root, "package.json"), "utf8"));
+  return JSON.parse(readFileSync6(join8(root, "package.json"), "utf8"));
 }
 function sortedKeys(value) {
   return Object.keys(value ?? {}).sort((left, right) => left.localeCompare(right));
@@ -24106,11 +24691,13 @@ export {
   upsertEncryptionProfile,
   updateRoadmap,
   updateMilestone,
+  todosAiExitCodeForResult,
   summarizeRoadmap,
   summarizeMilestone,
   sealLocalAuditLedger,
   returnReviewItem,
   restoreLocalBackup,
+  resolveTodosAiCommandOptions,
   requestReviewQueue,
   reopenReviewItem,
   renderRoadmapMarkdown,
@@ -24124,7 +24711,12 @@ export {
   readTesterIssueReportsPayload,
   readLocalBackupFile,
   pollLocalSnapshots,
+  parseTodosAiVariables,
+  parseTodosAiOutputSchema,
+  parseTodosAiJson,
+  normalizeTodosAiPrompt,
   normalizeTesterIssueReport,
+  loadTodosAiRuntime,
   listSdkIntegrationExamples,
   listRoadmaps,
   listReviewRoutingRules,
@@ -24136,6 +24728,10 @@ export {
   listLocalReportTypes,
   listLocalAuditLedgerCheckpoints,
   listEncryptionProfiles,
+  isTodosAiUpdateTaskResult,
+  isTodosAiRuntimeEvent,
+  isTodosAiRunResult,
+  isTodosAiJsonValue,
   isEncryptedValue,
   isEncryptedBridgeBundle,
   importRoadmapBundle,
@@ -24159,6 +24755,9 @@ export {
   decryptValue,
   decryptString,
   decryptBridgeBundle,
+  createTodosAiNeedsInputResult,
+  createTodosAiNeedsApprovalResult,
+  createTodosAiFailureResult,
   createSdkIntegrationFixturePack,
   createRoadmap,
   createReleaseCompatibilityReport,
@@ -24173,7 +24772,12 @@ export {
   claimReviewItem,
   checkLocalNotifications,
   checkLocalIntegrity,
+  assertTodosAiRuntimeModule,
+  assertTodosAiRunResult,
   approveReviewItem,
+  TodosAiNeedsInputSignal,
+  TodosAiNeedsApprovalSignal,
+  TodosAiContractError,
   TODOS_SDK_INTEGRATION_FIXTURE_SCHEMA_VERSION,
   TODOS_SDK_INTEGRATION_FIXTURE_GENERATED_AT,
   TODOS_ONBOARDING_FIXTURE_SOURCE,
@@ -24193,6 +24797,22 @@ export {
   TODOS_ENCRYPTED_BRIDGE_KIND,
   TODOS_CONTRACTS,
   TODOS_API_ROUTES,
+  TODOS_AI_WRITE_MODES,
+  TODOS_AI_UPDATE_TASK_RESULT_SCHEMA,
+  TODOS_AI_UPDATE_TASK_LIMITS,
+  TODOS_AI_UPDATE_TASK_FIELDS,
+  TODOS_AI_TOOL_EFFECTS,
+  TODOS_AI_SCHEMA_VERSION,
+  TODOS_AI_RUN_STATUSES,
+  TODOS_AI_RUNTIME_SPECIFIER,
+  TODOS_AI_RUNTIME_PROTOCOL_VERSION,
+  TODOS_AI_RUNTIME_EVENT_TYPES,
+  TODOS_AI_PROTOCOL,
+  TODOS_AI_LIMITS,
+  TODOS_AI_FORMATS,
+  TODOS_AI_EXIT_CODES,
+  TODOS_AI_DEFAULTS,
+  TODOS_AI_APPROVAL_MODES,
   TESTERS_ISSUE_REPORT_SCHEMA_VERSION,
   TESTERS_ISSUE_REPORT_RESULT_SCHEMA_VERSION,
   TESTERS_ISSUE_REPORT_BATCH_RESULT_SCHEMA_VERSION,