@kohala/devkit 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,2246 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { createRequire } from "module";
+import { Command } from "commander";
+import pc10 from "picocolors";
+
+// src/cli/init.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import pc from "picocolors";
+
+// src/manifest/schema.ts
+import { z } from "zod";
+var BILLING_PERIODS = ["day", "week", "month"];
+var shapeValidatorSchema = z.object({
+  type: z.literal("shape"),
+  minBytes: z.number().int().nonnegative()
+}).strict();
+var freshnessValidatorSchema = z.object({
+  type: z.literal("freshness"),
+  /** Logical memory key of the asset that must be fresh. */
+  asset: z.string().min(1),
+  maxAgeHours: z.number().positive()
+}).strict();
+var invariantValidatorSchema = z.object({
+  type: z.literal("invariant"),
+  /** JavaScript-flavored regular expression source (no delimiters). */
+  pattern: z.string().min(1),
+  /** When false, the output must NOT match the pattern. Defaults to true. */
+  mustMatch: z.boolean().default(true)
+}).strict();
+var validatorSchema = z.discriminatedUnion("type", [
+  shapeValidatorSchema,
+  freshnessValidatorSchema,
+  invariantValidatorSchema
+]);
+var capsSchema = z.object({
+  /** Hard token ceiling for a single shift (platform: agentPerRunTokenCap). */
+  perRunTokens: z.number().int().positive(),
+  /** Cumulative token ceiling per UTC day (platform: agentPerDayTokenCap). */
+  perDayTokens: z.number().int().positive(),
+  /** Billing-period token cap (platform: agentBillingCapTokens). Ignored locally. */
+  billingTokens: z.number().int().positive().optional(),
+  /** Billing period for billingTokens (platform: agentBillingCapPeriod). */
+  billingPeriod: z.enum(BILLING_PERIODS).optional()
+}).strict().refine((caps) => caps.billingTokens === void 0 || caps.billingPeriod !== void 0, {
+  message: "caps.billingPeriod is required when caps.billingTokens is set",
+  path: ["billingPeriod"]
+});
+var nameSchema = z.string().min(1).max(64).regex(
+  /^[a-z0-9][a-z0-9_-]*$/i,
+  "must start with a letter or digit and contain only letters, digits, '-' and '_'"
+);
+var manifestSchema = z.object({
+  name: nameSchema,
+  /** The agent's mission text (platform: agentCharter). */
+  charter: z.string().min(1),
+  /**
+   * Tools the agent may call, e.g. ["s3.put", "http.post_json"].
+   * Everything not on this list is denied loudly at runtime.
+   */
+  toolAllowlist: z.array(z.string().min(1)).default([]),
+  /**
+   * "wrap"  — execute the skill script directly and validate its output.
+   * "llm"   — run a real tool-use loop against the developer's own LLM key.
+   */
+  runtimeMode: z.enum(["wrap", "llm"]),
+  /** Map of skill name -> script filename, e.g. {"collect": "main.py"}. */
+  skills: z.record(z.string().min(1), z.string().min(1)).default({}),
+  /** Cron expression. Used only on deploy; local runs are always manual. */
+  schedule: z.string().min(1).optional(),
+  caps: capsSchema,
+  validators: z.array(validatorSchema).default([])
+}).strict();
+
+// src/cli/init.ts
+function templatesDir() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path.resolve(here, "..", "..", "templates"),
+    path.resolve(here, "..", "..", "..", "templates")
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(candidate, "kohala.json"))) return candidate;
+  }
+  throw new Error(`Could not locate the devkit templates directory (looked in: ${candidates.join(", ")})`);
+}
+function copyTemplates(sourceDir, targetDir, agentName) {
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      copyTemplates(sourcePath, targetPath, agentName);
+    } else {
+      const contents = fs.readFileSync(sourcePath, "utf8");
+      fs.writeFileSync(targetPath, contents.replaceAll("{{AGENT_NAME}}", agentName), "utf8");
+    }
+  }
+}
+function registerInitCommand(program2) {
+  program2.command("init").argument("<name>", "agent name (also the directory name)").description("Scaffold a new agent: kohala.json, a working skill, and the local SDK").action((name) => {
+    const nameCheck = manifestSchema.shape.name.safeParse(name);
+    if (!nameCheck.success) {
+      throw new Error(
+        `"${name}" is not a valid agent name: ${nameCheck.error.issues[0]?.message ?? "invalid"}`
+      );
+    }
+    const targetDir = path.resolve(process.cwd(), name);
+    if (fs.existsSync(targetDir)) {
+      throw new Error(`${targetDir} already exists \u2014 pick a new name or remove the directory.`);
+    }
+    copyTemplates(templatesDir(), targetDir, name);
+    console.log(pc.green(`Created agent "${name}" in ${targetDir}`));
+    console.log("");
+    console.log("Next steps:");
+    console.log(pc.cyan(`  kohala validate ${name}`));
+    console.log(pc.cyan(`  kohala run ${name} --local`));
+    console.log(pc.cyan(`  kohala trace ${name}`));
+  });
+}
+
+// src/cli/validate.ts
+import path3 from "path";
+import pc2 from "picocolors";
+
+// src/manifest/load.ts
+import fs2 from "fs";
+import path2 from "path";
+var ManifestError = class extends Error {
+  /** One human-readable problem per line, each with a fix hint when we have one. */
+  problems;
+  constructor(message, problems = []) {
+    super(message);
+    this.name = "ManifestError";
+    this.problems = problems;
+  }
+};
+var FIELD_HINTS = {
+  name: 'use a short identifier like "my-agent" (letters, digits, "-", "_")',
+  charter: "write the agent's mission as a non-empty string",
+  toolAllowlist: 'list allowed tool names, e.g. ["s3.put", "http.post_json"]',
+  runtimeMode: 'must be "wrap" (script wrapper) or "llm" (tool-use loop)',
+  skills: 'map skill name to script filename, e.g. {"collect": "main.py"}',
+  schedule: 'use a cron expression like "0 9 * * *" (only used on deploy)',
+  caps: "set caps.perRunTokens and caps.perDayTokens as positive integers",
+  validators: 'each validator needs a "type" of "shape", "freshness" or "invariant"'
+};
+function formatIssue(issue) {
+  const issuePath = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+  const topLevelField = String(issue.path[0] ?? "");
+  const hint = FIELD_HINTS[topLevelField];
+  const hintSuffix = hint ? ` (hint: ${hint})` : "";
+  return `${issuePath}: ${issue.message}${hintSuffix}`;
+}
+function formatManifestIssues(error) {
+  return error.issues.map(formatIssue);
+}
+function manifestPath(agentDir) {
+  return path2.join(agentDir, "kohala.json");
+}
+function loadManifest(agentDir) {
+  const filePath = manifestPath(agentDir);
+  if (!fs2.existsSync(filePath)) {
+    throw new ManifestError(
+      `No kohala.json found at ${filePath}`,
+      [`create one with: kohala init ${path2.basename(agentDir) || "<name>"}`]
+    );
+  }
+  let raw;
+  try {
+    raw = fs2.readFileSync(filePath, "utf8");
+  } catch (error) {
+    throw new ManifestError(`Could not read ${filePath}: ${error.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new ManifestError(`${filePath} is not valid JSON: ${error.message}`, [
+      "check for trailing commas or missing quotes"
+    ]);
+  }
+  const result = manifestSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new ManifestError(`${filePath} failed validation`, formatManifestIssues(result.error));
+  }
+  return result.data;
+}
+
+// src/cli/validate.ts
+function registerValidateCommand(program2) {
+  program2.command("validate").argument("<agent>", "agent directory (containing kohala.json)").description("Validate an agent's kohala.json and print precise errors").action((agent) => {
+    const agentDir = path3.resolve(process.cwd(), agent);
+    try {
+      const manifest = loadManifest(agentDir);
+      console.log(pc2.green(`kohala.json for "${manifest.name}" is valid.`));
+      console.log(
+        pc2.dim(
+          `  runtimeMode=${manifest.runtimeMode} skills=${Object.keys(manifest.skills).length} validators=${manifest.validators.length} allowlist=[${manifest.toolAllowlist.join(", ")}]`
+        )
+      );
+    } catch (error) {
+      if (error instanceof ManifestError) {
+        console.error(pc2.red(error.message));
+        for (const problem of error.problems) {
+          console.error(pc2.red(`  \u2022 ${problem}`));
+        }
+        process.exitCode = 1;
+        return;
+      }
+      throw error;
+    }
+  });
+}
+
+// src/cli/run.ts
+import path9 from "path";
+import pc3 from "picocolors";
+
+// src/memory/file.ts
+import crypto from "crypto";
+import fs4 from "fs";
+import path5 from "path";
+
+// src/memory/store.ts
+var DEFAULT_CATEGORY = "agentoutput";
+var DEFAULT_LIST_LIMIT = 100;
+
+// src/util/lock.ts
+import fs3 from "fs";
+import path4 from "path";
+var STALE_MS = 1e4;
+var ACQUIRE_TIMEOUT_MS = 5e3;
+var RETRY_DELAY_MS = 15;
+function sleep(ms) {
+  const buffer = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(buffer), 0, 0, ms);
+}
+function withFileLock(filePath, fn) {
+  const lockDir = `${filePath}.lock`;
+  fs3.mkdirSync(path4.dirname(lockDir), { recursive: true });
+  const deadline = Date.now() + ACQUIRE_TIMEOUT_MS;
+  for (; ; ) {
+    try {
+      fs3.mkdirSync(lockDir);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      try {
+        const age = Date.now() - fs3.statSync(lockDir).mtimeMs;
+        if (age > STALE_MS) {
+          fs3.rmdirSync(lockDir);
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() > deadline) {
+        throw new Error(
+          `Timed out waiting for lock ${lockDir} \u2014 another kohala process is holding it. If no other process is running, delete the directory and retry.`,
+          { cause: error }
+        );
+      }
+      sleep(RETRY_DELAY_MS);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    try {
+      fs3.rmdirSync(lockDir);
+    } catch {
+    }
+  }
+}
+function atomicWriteFile(filePath, content) {
+  fs3.mkdirSync(path4.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.tmp`;
+  fs3.writeFileSync(tempPath, content, "utf8");
+  fs3.renameSync(tempPath, filePath);
+}
+
+// src/memory/file.ts
+function memoryDirFor(rootDir, agent) {
+  return path5.join(rootDir, ".kohala", "memory", agent);
+}
+var FileMemoryStore = class {
+  dir;
+  indexPath;
+  bodiesDir;
+  constructor(rootDir, agent) {
+    this.dir = memoryDirFor(rootDir, agent);
+    this.indexPath = path5.join(this.dir, "index.json");
+    this.bodiesDir = path5.join(this.dir, "bodies");
+    fs4.mkdirSync(this.bodiesDir, { recursive: true });
+  }
+  readIndex() {
+    if (!fs4.existsSync(this.indexPath)) {
+      return { records: [] };
+    }
+    const raw = fs4.readFileSync(this.indexPath, "utf8");
+    return JSON.parse(raw);
+  }
+  writeIndex(index) {
+    atomicWriteFile(this.indexPath, JSON.stringify(index, null, 2));
+  }
+  bodyPath(id) {
+    return path5.join(this.bodiesDir, id);
+  }
+  async put(key, body, category = DEFAULT_CATEGORY) {
+    return withFileLock(this.indexPath, () => {
+      const index = this.readIndex();
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const existing = index.records.find((record2) => record2.active && record2.key === key);
+      if (existing) {
+        existing.category = category;
+        existing.size = body.byteLength;
+        existing.updatedAt = now;
+        fs4.writeFileSync(this.bodyPath(existing.id), body);
+        this.writeIndex(index);
+        return { ...existing };
+      }
+      const record = {
+        id: crypto.randomUUID(),
+        key,
+        category,
+        size: body.byteLength,
+        createdAt: now,
+        updatedAt: now,
+        active: true
+      };
+      fs4.writeFileSync(this.bodyPath(record.id), body);
+      index.records.push(record);
+      this.writeIndex(index);
+      return { ...record };
+    });
+  }
+  async get(keyOrId) {
+    const index = this.readIndex();
+    const record = index.records.find((entry) => entry.active && entry.key === keyOrId) ?? index.records.find((entry) => entry.active && entry.id === keyOrId);
+    if (!record) return null;
+    const filePath = this.bodyPath(record.id);
+    if (!fs4.existsSync(filePath)) {
+      throw new Error(
+        `Memory index lists ${record.key} (${record.id}) but its body file is missing at ${filePath}`
+      );
+    }
+    return { record: { ...record }, body: fs4.readFileSync(filePath) };
+  }
+  async list(prefix, limit = DEFAULT_LIST_LIMIT) {
+    const index = this.readIndex();
+    return index.records.filter((record) => record.active && (prefix === void 0 || record.key.startsWith(prefix))).sort((a, b) => a.updatedAt < b.updatedAt ? 1 : -1).slice(0, limit).map((record) => ({ ...record }));
+  }
+  async delete(keyOrId) {
+    return withFileLock(this.indexPath, () => {
+      const index = this.readIndex();
+      const record = index.records.find((entry) => entry.active && entry.key === keyOrId) ?? index.records.find((entry) => entry.active && entry.id === keyOrId);
+      if (!record) return null;
+      record.active = false;
+      record.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const filePath = this.bodyPath(record.id);
+      if (fs4.existsSync(filePath)) {
+        fs4.unlinkSync(filePath);
+      }
+      this.writeIndex(index);
+      return { ...record };
+    });
+  }
+  async close() {
+  }
+};
+
+// src/memory/postgres.ts
+import crypto2 from "crypto";
+function rowToRecord(row) {
+  return {
+    id: row.id,
+    key: row.key,
+    category: row.category,
+    size: Number(row.size),
+    createdAt: new Date(row.created_at).toISOString(),
+    updatedAt: new Date(row.updated_at).toISOString(),
+    active: row.active
+  };
+}
+var PostgresMemoryStore = class _PostgresMemoryStore {
+  constructor(pool, agent) {
+    this.pool = pool;
+    this.agent = agent;
+  }
+  pool;
+  agent;
+  /** Connect, run the idempotent migration, and return a ready store. */
+  static async connect(url, agent) {
+    let pgModule;
+    try {
+      pgModule = await import("pg");
+    } catch {
+      throw new Error(
+        'The postgres backend requires the optional "pg" package. Install it with: npm install pg'
+      );
+    }
+    const PoolCtor = pgModule.default?.Pool ?? pgModule.Pool;
+    const pool = new PoolCtor({ connectionString: url });
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS kohala_memory (
+        id UUID PRIMARY KEY,
+        agent TEXT NOT NULL,
+        key TEXT NOT NULL,
+        category TEXT NOT NULL,
+        body BYTEA,
+        size BIGINT NOT NULL,
+        created_at TIMESTAMPTZ NOT NULL,
+        updated_at TIMESTAMPTZ NOT NULL,
+        active BOOLEAN NOT NULL DEFAULT TRUE
+      )
+    `);
+    await pool.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS kohala_memory_active_key
+      ON kohala_memory (agent, key) WHERE active
+    `);
+    return new _PostgresMemoryStore(pool, agent);
+  }
+  async put(key, body, category = DEFAULT_CATEGORY) {
+    const now = /* @__PURE__ */ new Date();
+    const existing = await this.pool.query(
+      "SELECT * FROM kohala_memory WHERE agent = $1 AND key = $2 AND active",
+      [this.agent, key]
+    );
+    if (existing.rows.length > 0) {
+      const row = existing.rows[0];
+      const updated = await this.pool.query(
+        `UPDATE kohala_memory SET category = $1, body = $2, size = $3, updated_at = $4
+         WHERE id = $5 RETURNING *`,
+        [category, body, body.byteLength, now, row.id]
+      );
+      return rowToRecord(updated.rows[0]);
+    }
+    const inserted = await this.pool.query(
+      `INSERT INTO kohala_memory (id, agent, key, category, body, size, created_at, updated_at, active)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $7, TRUE) RETURNING *`,
+      [crypto2.randomUUID(), this.agent, key, category, body, body.byteLength, now]
+    );
+    return rowToRecord(inserted.rows[0]);
+  }
+  async get(keyOrId) {
+    const byKey = await this.pool.query(
+      "SELECT * FROM kohala_memory WHERE agent = $1 AND key = $2 AND active",
+      [this.agent, keyOrId]
+    );
+    let row = byKey.rows[0];
+    if (!row && isUuid(keyOrId)) {
+      const byId = await this.pool.query(
+        "SELECT * FROM kohala_memory WHERE agent = $1 AND id = $2 AND active",
+        [this.agent, keyOrId]
+      );
+      row = byId.rows[0];
+    }
+    if (!row) return null;
+    return { record: rowToRecord(row), body: row.body ?? Buffer.alloc(0) };
+  }
+  async list(prefix, limit = DEFAULT_LIST_LIMIT) {
+    const result = prefix ? await this.pool.query(
+      `SELECT id, agent, key, category, NULL AS body, size, created_at, updated_at, active
+           FROM kohala_memory WHERE agent = $1 AND active AND key LIKE $2 || '%'
+           ORDER BY updated_at DESC LIMIT $3`,
+      [this.agent, prefix, limit]
+    ) : await this.pool.query(
+      `SELECT id, agent, key, category, NULL AS body, size, created_at, updated_at, active
+           FROM kohala_memory WHERE agent = $1 AND active
+           ORDER BY updated_at DESC LIMIT $2`,
+      [this.agent, limit]
+    );
+    return result.rows.map((row) => rowToRecord(row));
+  }
+  async delete(keyOrId) {
+    const asset = await this.get(keyOrId);
+    if (!asset) return null;
+    const updated = await this.pool.query(
+      `UPDATE kohala_memory SET active = FALSE, body = NULL, updated_at = $1
+       WHERE id = $2 RETURNING *`,
+      [/* @__PURE__ */ new Date(), asset.record.id]
+    );
+    return rowToRecord(updated.rows[0]);
+  }
+  async close() {
+    await this.pool.end();
+  }
+};
+function isUuid(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+}
+
+// src/memory/create.ts
+async function createMemoryStore(options) {
+  if (options.backend === "file") {
+    return new FileMemoryStore(options.rootDir ?? process.cwd(), options.agent);
+  }
+  if (!options.url) {
+    throw new Error(
+      "The postgres backend needs a connection string. Pass --url or set DATABASE_URL."
+    );
+  }
+  return PostgresMemoryStore.connect(options.url, options.agent);
+}
+
+// src/emulator/runner.ts
+import crypto3 from "crypto";
+import path8 from "path";
+import { execa as execa2, ExecaError } from "execa";
+
+// src/trace/writer.ts
+import fs5 from "fs";
+import path6 from "path";
+function traceFilePath(rootDir, agent) {
+  return path6.join(rootDir, ".kohala", "trace", `${agent}.jsonl`);
+}
+var TraceWriter = class {
+  filePath;
+  constructor(rootDir, agent) {
+    this.filePath = traceFilePath(rootDir, agent);
+    fs5.mkdirSync(path6.dirname(this.filePath), { recursive: true });
+  }
+  /** Append one event as a JSONL line. */
+  append(event) {
+    fs5.appendFileSync(this.filePath, `${JSON.stringify(event)}
+`, "utf8");
+  }
+  /** The file this writer appends to (used by `kohala trace`). */
+  get file() {
+    return this.filePath;
+  }
+};
+
+// src/emulator/tokens.ts
+import fs6 from "fs";
+import path7 from "path";
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function utcDay(now = /* @__PURE__ */ new Date()) {
+  return now.toISOString().slice(0, 10);
+}
+function usageFilePath(rootDir, agent) {
+  return path7.join(rootDir, ".kohala", "usage", `${agent}.json`);
+}
+function readUsage(rootDir, agent) {
+  const filePath = usageFilePath(rootDir, agent);
+  if (!fs6.existsSync(filePath)) return { days: {} };
+  return JSON.parse(fs6.readFileSync(filePath, "utf8"));
+}
+function writeUsage(rootDir, agent, usage) {
+  atomicWriteFile(usageFilePath(rootDir, agent), JSON.stringify(usage, null, 2));
+}
+var CapExceededError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CapExceededError";
+  }
+  code;
+};
+var TokenMeter = class {
+  constructor(rootDir, agent, caps) {
+    this.rootDir = rootDir;
+    this.agent = agent;
+    this.caps = caps;
+  }
+  rootDir;
+  agent;
+  caps;
+  /** Tokens consumed by this shift so far. */
+  runTotal = 0;
+  /** Set when a cap abort happened, so the runner can report the right status. */
+  abortedWith = null;
+  /** Tokens already consumed today (UTC), across all local runs. */
+  dayTotal() {
+    const usage = readUsage(this.rootDir, this.agent);
+    return usage.days[utcDay()] ?? 0;
+  }
+  /**
+   * Admission: refuse the shift before any work if today's local runs have
+   * already exhausted the per-day cap — the platform refuses the same way.
+   */
+  admitRun() {
+    const today = this.dayTotal();
+    if (today >= this.caps.perDayTokens) {
+      const error = new CapExceededError(
+        "PER_DAY_TOKEN_CAP",
+        `PER_DAY_TOKEN_CAP: today's usage (${today} tokens) has reached the per-day cap of ${this.caps.perDayTokens}. The cap resets at UTC midnight.`
+      );
+      this.abortedWith = error;
+      throw error;
+    }
+  }
+  /**
+   * Pre-turn projection: abort the run if `projectedTokens` more would cross
+   * the per-run cap. Called before every LLM turn (wrap-mode llm.complete
+   * calls and llm-mode loop turns alike).
+   */
+  admitLlmTurn(projectedTokens) {
+    if (this.runTotal + projectedTokens > this.caps.perRunTokens) {
+      const error = new CapExceededError(
+        "PER_RUN_TOKEN_CAP",
+        `PER_RUN_TOKEN_CAP: this turn is projected to use ~${projectedTokens} tokens, which would push the run total past the per-run cap of ${this.caps.perRunTokens} (used so far: ${this.runTotal}).`
+      );
+      this.abortedWith = error;
+      throw error;
+    }
+  }
+  /**
+   * Record actual consumption and persist it into today's ledger. Returns the
+   * new day total. The read-modify-write is guarded by an interprocess lock so
+   * overlapping runs can't lose each other's updates (which would undercount
+   * usage and let concurrent runs slip past the day cap).
+   */
+  add(tokens) {
+    this.runTotal += tokens;
+    return withFileLock(usageFilePath(this.rootDir, this.agent), () => {
+      const usage = readUsage(this.rootDir, this.agent);
+      const day = utcDay();
+      usage.days[day] = (usage.days[day] ?? 0) + tokens;
+      writeUsage(this.rootDir, this.agent, usage);
+      return usage.days[day];
+    });
+  }
+};
+
+// src/emulator/validators.ts
+async function evaluateValidators(validators, output, store, now = /* @__PURE__ */ new Date()) {
+  const results = [];
+  for (const validator of validators) {
+    switch (validator.type) {
+      case "shape": {
+        const bytes = Buffer.byteLength(output, "utf8");
+        const passed = bytes >= validator.minBytes;
+        results.push({
+          validator: "shape",
+          passed,
+          detail: passed ? `output is ${bytes} bytes (>= ${validator.minBytes})` : `output is ${bytes} bytes, expected at least ${validator.minBytes}`
+        });
+        break;
+      }
+      case "freshness": {
+        const asset = await store.get(validator.asset);
+        if (!asset) {
+          results.push({
+            validator: "freshness",
+            passed: false,
+            detail: `memory asset "${validator.asset}" does not exist`
+          });
+          break;
+        }
+        const ageHours = (now.getTime() - new Date(asset.record.updatedAt).getTime()) / 36e5;
+        const passed = ageHours <= validator.maxAgeHours;
+        results.push({
+          validator: "freshness",
+          passed,
+          detail: passed ? `asset "${validator.asset}" is ${ageHours.toFixed(2)}h old (<= ${validator.maxAgeHours}h)` : `asset "${validator.asset}" is ${ageHours.toFixed(2)}h old, must be newer than ${validator.maxAgeHours}h`
+        });
+        break;
+      }
+      case "invariant": {
+        let regex;
+        try {
+          regex = new RegExp(validator.pattern);
+        } catch (error) {
+          results.push({
+            validator: "invariant",
+            passed: false,
+            detail: `invalid regex "${validator.pattern}": ${error.message}`
+          });
+          break;
+        }
+        const matched = regex.test(output);
+        const passed = validator.mustMatch ? matched : !matched;
+        results.push({
+          validator: "invariant",
+          passed,
+          detail: passed ? `output ${validator.mustMatch ? "matches" : "does not match"} /${validator.pattern}/ as required` : `output ${matched ? "matches" : "does not match"} /${validator.pattern}/ but ${validator.mustMatch ? "must match" : "must NOT match"}`
+        });
+        break;
+      }
+    }
+  }
+  return results;
+}
+
+// src/sdk/rpc.ts
+import http from "http";
+
+// src/sdk/dispatch.ts
+import dns from "dns/promises";
+import net from "net";
+
+// src/emulator/allowlist.ts
+var ToolDeniedError = class extends Error {
+  constructor(tool, allowlist) {
+    super(
+      `TOOL_DENIED: "${tool}" is not in the agent's toolAllowlist [${allowlist.join(", ")}]. Add it to kohala.json if the agent should be able to use it.`
+    );
+    this.tool = tool;
+    this.name = "ToolDeniedError";
+  }
+  tool;
+};
+function isToolAllowed(allowlist, tool) {
+  return allowlist.includes(tool);
+}
+function assertToolAllowed(allowlist, tool) {
+  if (!isToolAllowed(allowlist, tool)) {
+    throw new ToolDeniedError(tool, allowlist);
+  }
+}
+
+// src/emulator/llm-client.ts
+var NoLlmKeyError = class extends Error {
+  constructor() {
+    super(
+      "NO_LLM_KEY: no LLM key configured. Set ANTHROPIC_API_KEY (preferred) or GEMINI_API_KEY in your environment \u2014 the devkit never mocks completions."
+    );
+    this.name = "NoLlmKeyError";
+  }
+};
+var DEFAULT_ANTHROPIC_MODEL = "claude-3-5-haiku-latest";
+var DEFAULT_GEMINI_MODEL = "gemini-2.0-flash";
+function detectLlmProvider(env = process.env) {
+  if (env.ANTHROPIC_API_KEY) return "anthropic";
+  if (env.GEMINI_API_KEY) return "gemini";
+  return null;
+}
+async function completeText(prompt, model, maxOutputTokens = 1024, env = process.env) {
+  const provider = detectLlmProvider(env);
+  if (provider === "anthropic") {
+    return completeAnthropic(prompt, model ?? DEFAULT_ANTHROPIC_MODEL, maxOutputTokens, env);
+  }
+  if (provider === "gemini") {
+    return completeGemini(prompt, model ?? DEFAULT_GEMINI_MODEL, maxOutputTokens, env);
+  }
+  throw new NoLlmKeyError();
+}
+async function completeAnthropic(prompt, model, maxOutputTokens, env) {
+  const response = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-api-key": env.ANTHROPIC_API_KEY,
+      "anthropic-version": "2023-06-01"
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: maxOutputTokens,
+      messages: [{ role: "user", content: prompt }]
+    })
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Anthropic API error ${response.status}: ${body.slice(0, 300)}`);
+  }
+  const data = await response.json();
+  const text = data.content.filter((block) => block.type === "text").map((block) => block.text ?? "").join("");
+  return {
+    text,
+    inputTokens: data.usage.input_tokens,
+    outputTokens: data.usage.output_tokens,
+    provider: "anthropic",
+    model
+  };
+}
+async function completeGemini(prompt, model, maxOutputTokens, env) {
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-goog-api-key": env.GEMINI_API_KEY
+    },
+    body: JSON.stringify({
+      contents: [{ parts: [{ text: prompt }] }],
+      generationConfig: { maxOutputTokens }
+    })
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Gemini API error ${response.status}: ${body.slice(0, 300)}`);
+  }
+  const data = await response.json();
+  const text = (data.candidates?.[0]?.content?.parts ?? []).map((part) => part.text ?? "").join("");
+  return {
+    text,
+    inputTokens: data.usageMetadata?.promptTokenCount ?? 0,
+    outputTokens: data.usageMetadata?.candidatesTokenCount ?? 0,
+    provider: "gemini",
+    model
+  };
+}
+
+// src/sdk/dispatch.ts
+var ToolCallError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ToolCallError";
+  }
+  code;
+};
+function summarizeArgs(args) {
+  const json = JSON.stringify(args) ?? "{}";
+  return json.length > 200 ? `${json.slice(0, 200)}\u2026` : json;
+}
+function isBlockedHostname(hostname) {
+  const lower = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (lower === "localhost" || lower.endsWith(".localhost")) return true;
+  if (net.isIP(lower)) return isBlockedIp(lower);
+  return false;
+}
+function isBlockedIp(ip) {
+  const version2 = net.isIP(ip);
+  if (version2 === 4) {
+    const octets = ip.split(".").map(Number);
+    const [a = 0, b = 0] = octets;
+    if (a === 0 || a === 10 || a === 127) return true;
+    if (a === 169 && b === 254) return true;
+    if (a === 172 && b >= 16 && b <= 31) return true;
+    if (a === 192 && b === 168) return true;
+    if (a === 100 && b >= 64 && b <= 127) return true;
+    return false;
+  }
+  if (version2 === 6) {
+    const lower = ip.toLowerCase();
+    if (lower === "::" || lower === "::1") return true;
+    if (lower.startsWith("fe8") || lower.startsWith("fe9") || lower.startsWith("fea") || lower.startsWith("feb"))
+      return true;
+    if (lower.startsWith("fc") || lower.startsWith("fd")) return true;
+    if (lower.startsWith("::ffff:")) {
+      const mapped = lower.slice("::ffff:".length);
+      return net.isIP(mapped) === 4 ? isBlockedIp(mapped) : true;
+    }
+    return false;
+  }
+  return true;
+}
+async function assertPublicHost(hostname) {
+  if (isBlockedHostname(hostname)) {
+    throw new ToolCallError(
+      "BLOCKED_HOST",
+      `http.post_json refuses internal/private hosts ("${hostname}") \u2014 same guard the platform applies.`
+    );
+  }
+  const bare = hostname.replace(/^\[|\]$/g, "");
+  if (net.isIP(bare)) return;
+  let addresses;
+  try {
+    addresses = await dns.lookup(bare, { all: true, verbatim: true });
+  } catch {
+    throw new ToolCallError("BAD_URL", `http.post_json could not resolve host "${hostname}"`);
+  }
+  for (const { address } of addresses) {
+    if (isBlockedIp(address)) {
+      throw new ToolCallError(
+        "BLOCKED_HOST",
+        `http.post_json refuses "${hostname}" \u2014 it resolves to the internal/private address ${address}.`
+      );
+    }
+  }
+}
+var MAX_REDIRECTS = 3;
+var ToolDispatcher = class _ToolDispatcher {
+  constructor(context) {
+    this.context = context;
+  }
+  context;
+  /** All tools the emulator knows how to execute. */
+  static KNOWN_TOOLS = [
+    "s3.put",
+    "s3.get",
+    "s3.list",
+    "s3.delete",
+    "http.post_json",
+    "llm.complete",
+    "notify.send",
+    "metrics.record"
+  ];
+  /**
+   * Execute `tool` with `args`. Always writes a tool_call trace event, whether
+   * the call was allowed, denied, or failed.
+   */
+  async call(tool, args) {
+    const { manifest, trace, runId } = this.context;
+    const startedAt = Date.now();
+    const base = {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      runId,
+      agent: manifest.name,
+      type: "tool_call",
+      tool,
+      argsSummary: summarizeArgs(args)
+    };
+    try {
+      assertToolAllowed(manifest.toolAllowlist, tool);
+    } catch (error) {
+      trace.append({
+        ...base,
+        allowed: false,
+        ok: false,
+        durationMs: Date.now() - startedAt,
+        error: error.message
+      });
+      throw new ToolCallError("TOOL_DENIED", error.message);
+    }
+    try {
+      const result = await this.execute(tool, args);
+      trace.append({ ...base, allowed: true, ok: true, durationMs: Date.now() - startedAt });
+      return result;
+    } catch (error) {
+      const message = error.message;
+      trace.append({
+        ...base,
+        allowed: true,
+        ok: false,
+        durationMs: Date.now() - startedAt,
+        error: message
+      });
+      if (error instanceof ToolCallError) throw error;
+      if (error instanceof CapExceededError) throw new ToolCallError(error.code, message);
+      throw new ToolCallError("TOOL_ERROR", message);
+    }
+  }
+  async execute(tool, args) {
+    const { store, meter, trace, manifest, runId } = this.context;
+    switch (tool) {
+      case "s3.put": {
+        const key = requireString(args, "key");
+        const body = requireString(args, "body");
+        const category = optionalString(args, "category");
+        const record = await store.put(key, Buffer.from(body, "utf8"), category);
+        return { record };
+      }
+      case "s3.get": {
+        const keyOrId = requireString(args, "keyOrId");
+        const asset = await store.get(keyOrId);
+        if (!asset) {
+          throw new ToolCallError("NOT_FOUND", `No active memory asset matches "${keyOrId}"`);
+        }
+        return { record: asset.record, body: asset.body.toString("utf8") };
+      }
+      case "s3.list": {
+        const prefix = optionalString(args, "prefix");
+        const limit = typeof args.limit === "number" ? args.limit : void 0;
+        const records = await store.list(prefix, limit);
+        return { records };
+      }
+      case "s3.delete": {
+        const keyOrId = requireString(args, "keyOrId");
+        const record = await store.delete(keyOrId);
+        if (!record) {
+          throw new ToolCallError("NOT_FOUND", `No active memory asset matches "${keyOrId}"`);
+        }
+        return { record };
+      }
+      case "http.post_json": {
+        const url = requireString(args, "url");
+        const headers = args.headers ?? {};
+        const requestBody = JSON.stringify(args.body ?? {});
+        let currentUrl = url;
+        let response;
+        for (let hop = 0; ; hop += 1) {
+          const parsed = safeParseUrl(currentUrl);
+          if (!parsed || parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            throw new ToolCallError(
+              "BAD_URL",
+              `http.post_json needs an http(s) URL, got "${currentUrl}"`
+            );
+          }
+          await assertPublicHost(parsed.hostname);
+          response = await fetch(currentUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...headers },
+            body: requestBody,
+            redirect: "manual"
+          });
+          if (response.status < 300 || response.status >= 400) break;
+          const location = response.headers.get("location");
+          if (!location) break;
+          if (hop >= MAX_REDIRECTS) {
+            throw new ToolCallError(
+              "TOO_MANY_REDIRECTS",
+              `http.post_json gave up after ${MAX_REDIRECTS} redirects (last: ${currentUrl})`
+            );
+          }
+          currentUrl = new URL(location, currentUrl).toString();
+        }
+        const text = await response.text();
+        let json = null;
+        try {
+          json = JSON.parse(text);
+        } catch {
+        }
+        return { status: response.status, ok: response.ok, body: text, json };
+      }
+      case "llm.complete": {
+        const prompt = requireString(args, "prompt");
+        const model = optionalString(args, "model");
+        const maxOutput = 1024;
+        meter.admitLlmTurn(estimateTokens(prompt) + maxOutput);
+        const completion = await completeText(prompt, model, maxOutput);
+        const consumed = completion.inputTokens + completion.outputTokens;
+        const dayTotal = meter.add(consumed);
+        trace.append({
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          runId,
+          agent: manifest.name,
+          type: "tokens",
+          tokens: consumed,
+          runTotal: meter.runTotal,
+          dayTotal,
+          source: `llm.complete ${completion.provider}/${completion.model}`
+        });
+        return {
+          text: completion.text,
+          model: completion.model,
+          provider: completion.provider,
+          inputTokens: completion.inputTokens,
+          outputTokens: completion.outputTokens
+        };
+      }
+      case "notify.send": {
+        requireString(args, "channel");
+        requireString(args, "message");
+        return { delivered: "trace" };
+      }
+      case "metrics.record": {
+        requireString(args, "name");
+        if (typeof args.value !== "number") {
+          throw new ToolCallError("BAD_ARGS", "metrics.record needs a numeric value");
+        }
+        return { recorded: "trace" };
+      }
+      default:
+        throw new ToolCallError(
+          "UNKNOWN_TOOL",
+          `Unknown tool "${tool}". Known tools: ${_ToolDispatcher.KNOWN_TOOLS.join(", ")}`
+        );
+    }
+  }
+};
+function requireString(args, name) {
+  const value = args[name];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new ToolCallError("BAD_ARGS", `Missing required string argument "${name}"`);
+  }
+  return value;
+}
+function optionalString(args, name) {
+  const value = args[name];
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "string") {
+    throw new ToolCallError("BAD_ARGS", `Argument "${name}" must be a string when provided`);
+  }
+  return value;
+}
+function safeParseUrl(url) {
+  try {
+    return new URL(url);
+  } catch {
+    return null;
+  }
+}
+
+// src/sdk/rpc.ts
+async function startSdkRpcServer(context) {
+  const dispatcher = new ToolDispatcher(context);
+  const server = http.createServer((request, response) => {
+    if (request.method !== "POST") {
+      response.writeHead(405, { "content-type": "application/json" });
+      response.end(JSON.stringify({ ok: false, error: { code: "METHOD_NOT_ALLOWED", message: "POST only" } }));
+      return;
+    }
+    let raw = "";
+    request.on("data", (chunk) => {
+      raw += chunk;
+    });
+    request.on("end", () => {
+      void (async () => {
+        let payload;
+        try {
+          payload = JSON.parse(raw);
+        } catch {
+          respond(response, { ok: false, error: { code: "BAD_JSON", message: "Request body is not valid JSON" } });
+          return;
+        }
+        if (typeof payload.tool !== "string") {
+          respond(response, { ok: false, error: { code: "BAD_REQUEST", message: 'Missing "tool" field' } });
+          return;
+        }
+        try {
+          const result = await dispatcher.call(
+            payload.tool,
+            payload.args ?? {}
+          );
+          respond(response, { ok: true, result });
+        } catch (error) {
+          if (error instanceof ToolCallError) {
+            respond(response, { ok: false, error: { code: error.code, message: error.message } });
+            return;
+          }
+          respond(response, {
+            ok: false,
+            error: { code: "INTERNAL", message: error.message }
+          });
+        }
+      })();
+    });
+  });
+  await new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  if (address === null || typeof address === "string") {
+    throw new Error("Could not determine RPC server port");
+  }
+  return {
+    url: `http://127.0.0.1:${address.port}`,
+    close: () => new Promise((resolve, reject) => {
+      server.close((error) => error ? reject(error) : resolve());
+    })
+  };
+}
+function respond(response, body) {
+  const json = JSON.stringify(body);
+  response.writeHead(200, { "content-type": "application/json" });
+  response.end(json);
+}
+
+// src/emulator/llm-mode.ts
+import fs7 from "fs";
+var MAX_TURNS = 16;
+var MAX_OUTPUT_TOKENS = 1024;
+var TOOL_DEFINITIONS = {
+  "s3.put": {
+    description: 'Store a value in agent memory under a logical key. Category defaults to "agentoutput".',
+    input_schema: {
+      type: "object",
+      properties: {
+        key: { type: "string" },
+        body: { type: "string" },
+        category: { type: "string" }
+      },
+      required: ["key", "body"]
+    }
+  },
+  "s3.get": {
+    description: "Fetch a memory asset by logical key (or record id).",
+    input_schema: {
+      type: "object",
+      properties: { keyOrId: { type: "string" } },
+      required: ["keyOrId"]
+    }
+  },
+  "s3.list": {
+    description: "List active memory assets, optionally filtered by key prefix.",
+    input_schema: {
+      type: "object",
+      properties: { prefix: { type: "string" }, limit: { type: "number" } }
+    }
+  },
+  "s3.delete": {
+    description: "Remove and deactivate a memory asset by key or id.",
+    input_schema: {
+      type: "object",
+      properties: { keyOrId: { type: "string" } },
+      required: ["keyOrId"]
+    }
+  },
+  "http.post_json": {
+    description: "POST a JSON body to an external http(s) URL and return the response.",
+    input_schema: {
+      type: "object",
+      properties: {
+        url: { type: "string" },
+        body: { type: "object" },
+        headers: { type: "object" }
+      },
+      required: ["url"]
+    }
+  },
+  "notify.send": {
+    description: "Send a notification (locally this is recorded in the audit trace).",
+    input_schema: {
+      type: "object",
+      properties: { channel: { type: "string" }, message: { type: "string" } },
+      required: ["channel", "message"]
+    }
+  },
+  "metrics.record": {
+    description: "Record a metric point (locally this is recorded in the audit trace).",
+    input_schema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        value: { type: "number" },
+        tags: { type: "object" }
+      },
+      required: ["name", "value"]
+    }
+  }
+};
+async function runLlmShift(context, skillName, scriptPath, repairFeedback) {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    throw new NoLlmKeyError();
+  }
+  const model = process.env.KOHALA_LLM_MODEL ?? "claude-3-5-haiku-latest";
+  const dispatcher = new ToolDispatcher(context);
+  const { manifest, meter, trace, runId } = context;
+  const tools = Object.entries(TOOL_DEFINITIONS).filter(([name]) => manifest.toolAllowlist.includes(name)).map(([name, definition]) => ({ name: toApiToolName(name), ...definition }));
+  const taskContext = fs7.existsSync(scriptPath) ? fs7.readFileSync(scriptPath, "utf8") : "";
+  const messages = [
+    {
+      role: "user",
+      content: `You are running one shift of the agent skill "${skillName}".
+` + (taskContext ? `Task instructions:
+${taskContext}
+` : "") + (repairFeedback ? `
+This is a repair attempt. Your previous output failed validation:
+${repairFeedback}
+Fix the problem this time.
+` : "") + "Use your tools as needed, then reply with a final text summary of what you did."
+    }
+  ];
+  for (let turn = 0; turn < MAX_TURNS; turn += 1) {
+    const projected = estimateTokens(JSON.stringify(messages) + manifest.charter) + MAX_OUTPUT_TOKENS;
+    meter.admitLlmTurn(projected);
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01"
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: MAX_OUTPUT_TOKENS,
+        system: manifest.charter,
+        tools,
+        messages
+      })
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`Anthropic API error ${response.status}: ${body.slice(0, 300)}`);
+    }
+    const data = await response.json();
+    const consumed = data.usage.input_tokens + data.usage.output_tokens;
+    const dayTotal = meter.add(consumed);
+    trace.append({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      runId,
+      agent: manifest.name,
+      type: "tokens",
+      tokens: consumed,
+      runTotal: meter.runTotal,
+      dayTotal,
+      source: `llm-mode turn ${turn + 1} (${model})`
+    });
+    const finalText = data.content.filter((block) => block.type === "text").map((block) => block.text ?? "").join("");
+    if (data.stop_reason !== "tool_use") {
+      return finalText;
+    }
+    messages.push({ role: "assistant", content: data.content });
+    const toolResults = [];
+    for (const block of data.content) {
+      if (block.type !== "tool_use" || !block.id || !block.name) continue;
+      const toolName = fromApiToolName(block.name);
+      try {
+        const result = await dispatcher.call(toolName, block.input ?? {});
+        toolResults.push({
+          type: "tool_result",
+          tool_use_id: block.id,
+          content: JSON.stringify(result).slice(0, 8e3)
+        });
+      } catch (error) {
+        const toolError = error;
+        toolResults.push({
+          type: "tool_result",
+          tool_use_id: block.id,
+          content: `${toolError.code ?? "TOOL_ERROR"}: ${toolError.message}`,
+          is_error: true
+        });
+      }
+    }
+    messages.push({ role: "user", content: toolResults });
+  }
+  throw new Error(`llm-mode shift exceeded ${MAX_TURNS} turns without finishing`);
+}
+function toApiToolName(name) {
+  return name.replace(/\./g, "__");
+}
+function fromApiToolName(name) {
+  return name.replace(/__/g, ".");
+}
+
+// src/emulator/python.ts
+import { execa } from "execa";
+var cachedPython = null;
+async function findPython() {
+  if (cachedPython) return cachedPython;
+  for (const candidate of ["python3", "python"]) {
+    try {
+      const result = await execa(candidate, ["--version"], { reject: false });
+      if (result.exitCode === 0 && /Python 3/.test(`${result.stdout}${result.stderr}`)) {
+        cachedPython = candidate;
+        return candidate;
+      }
+    } catch {
+    }
+  }
+  throw new Error(
+    "Python 3 is required to run agent skills but was not found on your PATH. Install it from https://www.python.org/downloads/ (or via your package manager: `brew install python3`, `apt install python3`), then re-run this command."
+  );
+}
+
+// src/emulator/runner.ts
+var MAX_REPAIR_ATTEMPTS = 2;
+function resolveSkill(manifest, requested) {
+  const entries = Object.entries(manifest.skills);
+  if (entries.length === 0) {
+    throw new Error(`Agent "${manifest.name}" has no skills in kohala.json`);
+  }
+  if (requested) {
+    const script = manifest.skills[requested];
+    if (!script) {
+      throw new Error(
+        `Skill "${requested}" not found. Available skills: ${entries.map(([name]) => name).join(", ")}`
+      );
+    }
+    return [requested, script];
+  }
+  if (entries.length === 1) {
+    return entries[0];
+  }
+  throw new Error(
+    `Agent "${manifest.name}" has ${entries.length} skills \u2014 pick one with --skill <name> (${entries.map(([name]) => name).join(", ")})`
+  );
+}
+async function runShift(options) {
+  const { rootDir, agentDir, manifest, store } = options;
+  const runId = `run_${Date.now().toString(36)}_${crypto3.randomBytes(3).toString("hex")}`;
+  const trace = new TraceWriter(rootDir, manifest.name);
+  const meter = new TokenMeter(rootDir, manifest.name, manifest.caps);
+  const startedAt = Date.now();
+  const [skillName, scriptFilename] = resolveSkill(manifest, options.skill);
+  const finish = (status, output, validatorResults, detail) => {
+    trace.append({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      runId,
+      agent: manifest.name,
+      type: "run_finished",
+      status,
+      totalTokens: meter.runTotal,
+      durationMs: Date.now() - startedAt,
+      ...detail ? { detail } : {}
+    });
+    return { runId, status, output, totalTokens: meter.runTotal, validatorResults, detail };
+  };
+  try {
+    meter.admitRun();
+  } catch (error) {
+    if (error instanceof CapExceededError) {
+      return finish("aborted_per_day_token_cap", "", [], error.message);
+    }
+    throw error;
+  }
+  trace.append({
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    runId,
+    agent: manifest.name,
+    type: "run_started",
+    runtimeMode: manifest.runtimeMode,
+    skill: skillName,
+    scriptFilename
+  });
+  const context = { manifest, store, trace, meter, runId };
+  if (manifest.runtimeMode === "llm") {
+    try {
+      let repairReason = "";
+      for (let attempt = 0; attempt <= MAX_REPAIR_ATTEMPTS; attempt += 1) {
+        if (attempt > 0) {
+          trace.append({
+            ts: (/* @__PURE__ */ new Date()).toISOString(),
+            runId,
+            agent: manifest.name,
+            type: "repair_attempt",
+            attempt,
+            maxAttempts: MAX_REPAIR_ATTEMPTS,
+            reason: repairReason
+          });
+        }
+        const output = await runLlmShift(
+          context,
+          skillName,
+          path8.join(agentDir, "skills", scriptFilename),
+          attempt > 0 ? repairReason : void 0
+        );
+        const validatorResults = await evaluateValidators(manifest.validators, output, store);
+        recordValidatorResults(trace, runId, manifest.name, validatorResults);
+        const failures = validatorResults.filter((result) => !result.passed);
+        if (failures.length === 0) {
+          return finish("succeeded", output, validatorResults);
+        }
+        repairReason = failures.map((failure) => `${failure.validator}: ${failure.detail}`).join("; ");
+        if (attempt === MAX_REPAIR_ATTEMPTS) {
+          return finish(
+            "failed",
+            output,
+            validatorResults,
+            `validators failed after ${MAX_REPAIR_ATTEMPTS} repair attempts: ${repairReason}`
+          );
+        }
+      }
+      throw new Error("repair loop exited without a result");
+    } catch (error) {
+      if (error instanceof CapExceededError || meter.abortedWith) {
+        const cap = error instanceof CapExceededError ? error : meter.abortedWith;
+        const status = cap.code === "PER_RUN_TOKEN_CAP" ? "aborted_per_run_token_cap" : "aborted_per_day_token_cap";
+        return finish(status, "", [], cap.message);
+      }
+      return finish("error", "", [], error.message);
+    }
+  }
+  const rpc = await startSdkRpcServer(context);
+  try {
+    let repairReason = "";
+    for (let attempt = 0; attempt <= MAX_REPAIR_ATTEMPTS; attempt += 1) {
+      if (attempt > 0) {
+        trace.append({
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          runId,
+          agent: manifest.name,
+          type: "repair_attempt",
+          attempt,
+          maxAttempts: MAX_REPAIR_ATTEMPTS,
+          reason: repairReason
+        });
+      }
+      const execution = await executeScript({
+        agentDir,
+        scriptFilename,
+        rpcUrl: rpc.url,
+        manifest,
+        runId,
+        repairAttempt: attempt,
+        repairFeedback: repairReason
+      });
+      if (!execution.ok) {
+        if (meter.abortedWith?.code === "PER_RUN_TOKEN_CAP") {
+          return finish("aborted_per_run_token_cap", execution.stdout, [], meter.abortedWith.message);
+        }
+        return finish("error", execution.stdout, [], execution.errorDetail);
+      }
+      const validatorResults = await evaluateValidators(
+        manifest.validators,
+        execution.stdout,
+        store
+      );
+      recordValidatorResults(trace, runId, manifest.name, validatorResults);
+      const failures = validatorResults.filter((result) => !result.passed);
+      if (failures.length === 0) {
+        return finish("succeeded", execution.stdout, validatorResults);
+      }
+      repairReason = failures.map((failure) => `${failure.validator}: ${failure.detail}`).join("; ");
+      if (attempt === MAX_REPAIR_ATTEMPTS) {
+        return finish("failed", execution.stdout, validatorResults, `validators failed after ${MAX_REPAIR_ATTEMPTS} repair attempts: ${repairReason}`);
+      }
+    }
+    throw new Error("repair loop exited without a result");
+  } finally {
+    await rpc.close();
+  }
+}
+function recordValidatorResults(trace, runId, agent, results) {
+  for (const result of results) {
+    trace.append({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      runId,
+      agent,
+      type: "validator_result",
+      validator: result.validator,
+      passed: result.passed,
+      detail: result.detail
+    });
+  }
+}
+async function executeScript(options) {
+  const python = await findPython();
+  const scriptPath = path8.join(options.agentDir, "skills", options.scriptFilename);
+  try {
+    const result = await execa2(python, [scriptPath], {
+      cwd: options.agentDir,
+      env: {
+        KOHALA_RPC_URL: options.rpcUrl,
+        KOHALA_AGENT: options.manifest.name,
+        KOHALA_RUN_ID: options.runId,
+        KOHALA_REPAIR_ATTEMPT: String(options.repairAttempt),
+        KOHALA_VALIDATOR_FEEDBACK: options.repairFeedback
+      },
+      // Surface the script's stderr live so developers see their own logging.
+      stderr: "inherit",
+      reject: false,
+      timeout: 10 * 60 * 1e3
+    });
+    if (result.exitCode !== 0) {
+      return {
+        ok: false,
+        stdout: result.stdout ?? "",
+        errorDetail: `script ${options.scriptFilename} exited with code ${result.exitCode}`
+      };
+    }
+    return { ok: true, stdout: result.stdout ?? "" };
+  } catch (error) {
+    const message = error instanceof ExecaError ? error.message : error.message;
+    return { ok: false, stdout: "", errorDetail: message };
+  }
+}
+
+// src/cli/run.ts
+function registerRunCommand(program2) {
+  program2.command("run").argument("<agent>", "agent directory (containing kohala.json)").option("--local", "run against the local emulator (required for now)").option("--skill <name>", "which skill to run (defaults to the only skill)").option(
+    "--backend <backend>",
+    "memory backend for this run: file | postgres",
+    "file"
+  ).option("--url <url>", "postgres connection string (or set DATABASE_URL)").description("Run a shift against the local emulator").action(
+    async (agent, options) => {
+      if (!options.local) {
+        throw new Error(
+          "Hosted runs start from the platform, not the CLI. Use --local to run against the local emulator, or `kohala deploy --run` to trigger a hosted run."
+        );
+      }
+      if (options.backend !== "file" && options.backend !== "postgres") {
+        throw new Error(`Unknown backend "${options.backend}" \u2014 use "file" or "postgres".`);
+      }
+      const rootDir = process.cwd();
+      const agentDir = path9.resolve(rootDir, agent);
+      const manifest = loadManifest(agentDir);
+      const store = await createMemoryStore({
+        backend: options.backend,
+        agent: manifest.name,
+        rootDir,
+        url: options.url ?? process.env.DATABASE_URL
+      });
+      try {
+        console.log(
+          pc3.cyan(`Running shift for "${manifest.name}" (${manifest.runtimeMode} mode)...`)
+        );
+        const result = await runShift({ rootDir, agentDir, manifest, store, skill: options.skill });
+        console.log("");
+        if (result.status === "succeeded") {
+          console.log(pc3.green(`\u2714 Shift ${result.runId} succeeded`));
+        } else {
+          console.log(pc3.red(`\u2718 Shift ${result.runId} ${result.status.replace(/_/g, " ")}`));
+          if (result.detail) console.log(pc3.red(`  ${result.detail}`));
+        }
+        console.log(pc3.dim(`  tokens used: ${result.totalTokens} (counted, never billed)`));
+        for (const validator of result.validatorResults) {
+          const mark = validator.passed ? pc3.green("passed") : pc3.red("failed");
+          console.log(pc3.dim(`  validator ${validator.validator}: `) + mark + pc3.dim(` \u2014 ${validator.detail}`));
+        }
+        if (result.output.trim() !== "") {
+          console.log("");
+          console.log(pc3.dim("\u2500\u2500 output \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+          console.log(result.output.trim());
+        }
+        console.log("");
+        console.log(pc3.dim(`Full audit trail: kohala trace ${agent}`));
+        if (result.status !== "succeeded") {
+          process.exitCode = 1;
+        }
+      } finally {
+        await store.close();
+      }
+    }
+  );
+}
+
+// src/cli/trace.ts
+import fs9 from "fs";
+import path10 from "path";
+import pc5 from "picocolors";
+
+// src/trace/reader.ts
+import fs8 from "fs";
+function readTraceFile(filePath) {
+  const raw = fs8.readFileSync(filePath, "utf8");
+  return parseTraceLines(raw);
+}
+function parseTraceLines(raw) {
+  const events = [];
+  const lines = raw.split("\n");
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = (lines[i] ?? "").trim();
+    if (line === "") continue;
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+      throw new Error(`Malformed trace line ${i + 1}: ${line.slice(0, 120)}`);
+    }
+  }
+  return events;
+}
+function followTraceFile(filePath, onEvent, pollMs = 250) {
+  let offset = fs8.existsSync(filePath) ? fs8.statSync(filePath).size : 0;
+  let partial = "";
+  const timer = setInterval(() => {
+    if (!fs8.existsSync(filePath)) return;
+    const size = fs8.statSync(filePath).size;
+    if (size <= offset) return;
+    const stream = fs8.createReadStream(filePath, { start: offset, end: size - 1, encoding: "utf8" });
+    let chunkData = "";
+    stream.on("data", (chunk) => {
+      chunkData += chunk;
+    });
+    stream.on("end", () => {
+      offset = size;
+      partial += chunkData;
+      const lines = partial.split("\n");
+      partial = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === "") continue;
+        try {
+          onEvent(JSON.parse(trimmed));
+        } catch {
+          throw new Error(`Malformed trace line while following: ${trimmed.slice(0, 120)}`);
+        }
+      }
+    });
+  }, pollMs);
+  return () => clearInterval(timer);
+}
+
+// src/trace/format.ts
+import pc4 from "picocolors";
+function shortTime(ts) {
+  const date = new Date(ts);
+  return date.toLocaleTimeString("en-US", { hour12: false });
+}
+function formatTraceEvent(event) {
+  const time = pc4.dim(shortTime(event.ts));
+  switch (event.type) {
+    case "run_started":
+      return `${time} ${pc4.cyan("run_started")} skill=${event.skill} (${event.scriptFilename}) mode=${event.runtimeMode} run=${event.runId}`;
+    case "tool_call": {
+      const verdict = event.allowed ? event.ok ? pc4.green("ok") : pc4.red("error") : pc4.red("DENIED");
+      const errorSuffix = event.error ? ` ${pc4.red(event.error)}` : "";
+      return `${time} ${pc4.magenta("tool_call")} ${pc4.bold(event.tool)} ${verdict} ${pc4.dim(`${event.durationMs}ms`)} ${pc4.dim(event.argsSummary)}${errorSuffix}`;
+    }
+    case "tokens":
+      return `${time} ${pc4.dim(`tokens +${event.tokens} run=${event.runTotal} day=${event.dayTotal} (${event.source})`)}`;
+    case "validator_result": {
+      const verdict = event.passed ? pc4.green("passed") : pc4.red("FAILED");
+      return `${time} ${pc4.yellow("validator")} ${event.validator} ${verdict} ${pc4.dim(event.detail)}`;
+    }
+    case "repair_attempt":
+      return `${time} ${pc4.yellow(`repair_attempt ${event.attempt}/${event.maxAttempts}`)} ${pc4.dim(event.reason)}`;
+    case "run_finished": {
+      const color = event.status === "succeeded" ? pc4.green : event.status === "failed" ? pc4.red : pc4.red;
+      const detailSuffix = event.detail ? ` ${pc4.dim(event.detail)}` : "";
+      return `${time} ${color(`run_finished ${event.status}`)} tokens=${event.totalTokens} ${pc4.dim(`${event.durationMs}ms`)}${detailSuffix}`;
+    }
+  }
+}
+
+// src/cli/trace.ts
+function registerTraceCommand(program2) {
+  program2.command("trace").argument("<agent>", "agent directory or agent name").option("--follow", "keep watching for new events (like tail -f)").option("--json", "print raw JSONL events instead of the pretty view").description("Tail the audit trace for an agent").action((agent, options) => {
+    const rootDir = process.cwd();
+    let agentName = agent;
+    const agentDir = path10.resolve(rootDir, agent);
+    if (fs9.existsSync(path10.join(agentDir, "kohala.json"))) {
+      agentName = loadManifest(agentDir).name;
+    }
+    const filePath = traceFilePath(rootDir, agentName);
+    if (!fs9.existsSync(filePath)) {
+      throw new Error(
+        `No trace found for "${agentName}" (looked at ${filePath}). Run the agent first: kohala run ${agent} --local`
+      );
+    }
+    const print = options.json ? (event) => console.log(JSON.stringify(event)) : (event) => console.log(formatTraceEvent(event));
+    for (const event of readTraceFile(filePath)) {
+      print(event);
+    }
+    if (options.follow) {
+      console.error(pc5.dim(`\u2014 following ${filePath} (ctrl-c to stop) \u2014`));
+      followTraceFile(filePath, print);
+    }
+  });
+}
+
+// src/cli/memory-serve.ts
+import fs10 from "fs";
+import path11 from "path";
+import pc6 from "picocolors";
+
+// src/mcp/server.ts
+import http2 from "http";
+import { z as z2 } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+var SERVER_INFO = { name: "kohala-memory", version: "0.1.0" };
+function buildMemoryMcpServer(store, agent) {
+  const server = new McpServer(SERVER_INFO);
+  server.registerTool(
+    "s3.put",
+    {
+      title: "Store memory asset",
+      description: `Store a value in ${agent}'s persistent memory under a logical key. Category defaults to "${DEFAULT_CATEGORY}" (run results).`,
+      inputSchema: {
+        key: z2.string().min(1).describe("Logical key, e.g. weather/latest"),
+        body: z2.string().describe("UTF-8 body to store"),
+        category: z2.string().optional().describe(`Asset category (default "${DEFAULT_CATEGORY}")`)
+      }
+    },
+    async ({ key, body, category }) => {
+      const record = await store.put(key, Buffer.from(body, "utf8"), category);
+      return { content: [{ type: "text", text: JSON.stringify({ record }, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "s3.get",
+    {
+      title: "Fetch memory asset",
+      description: "Fetch an asset by logical key (resolved first) or record id.",
+      inputSchema: {
+        keyOrId: z2.string().min(1).describe("Logical key or record id")
+      }
+    },
+    async ({ keyOrId }) => {
+      const asset = await store.get(keyOrId);
+      if (!asset) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `No active memory asset matches "${keyOrId}"` }]
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { record: asset.record, body: asset.body.toString("utf8") },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "s3.list",
+    {
+      title: "List memory assets",
+      description: "List active assets for the agent, newest first, optionally by key prefix.",
+      inputSchema: {
+        prefix: z2.string().optional().describe("Only keys starting with this prefix"),
+        limit: z2.number().int().positive().optional().describe("Max records (default 100)")
+      }
+    },
+    async ({ prefix, limit }) => {
+      const records = await store.list(prefix, limit);
+      return { content: [{ type: "text", text: JSON.stringify({ records }, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "s3.delete",
+    {
+      title: "Delete memory asset",
+      description: "Remove an asset's body and deactivate its index entry (soft delete).",
+      inputSchema: {
+        keyOrId: z2.string().min(1).describe("Logical key or record id")
+      }
+    },
+    async ({ keyOrId }) => {
+      const record = await store.delete(keyOrId);
+      if (!record) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `No active memory asset matches "${keyOrId}"` }]
+        };
+      }
+      return { content: [{ type: "text", text: JSON.stringify({ record }, null, 2) }] };
+    }
+  );
+  server.registerResource(
+    "memory-index",
+    "memory://index",
+    {
+      title: `Memory index for ${agent}`,
+      description: "All active memory assets for this agent (key, category, timestamps).",
+      mimeType: "application/json"
+    },
+    async (uri) => {
+      const records = await store.list(void 0, 1e3);
+      return {
+        contents: [
+          { uri: uri.href, mimeType: "application/json", text: JSON.stringify({ agent, records }, null, 2) }
+        ]
+      };
+    }
+  );
+  return server;
+}
+async function serveStdio(store, agent) {
+  const server = buildMemoryMcpServer(store, agent);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+async function serveHttp(store, agent, port) {
+  const httpServer = http2.createServer((request, response) => {
+    void (async () => {
+      const url = new URL(request.url ?? "/", "http://127.0.0.1");
+      if (url.pathname !== "/mcp") {
+        response.writeHead(404, { "content-type": "application/json" });
+        response.end(JSON.stringify({ error: "Not found. The MCP endpoint is POST /mcp" }));
+        return;
+      }
+      if (request.method !== "POST") {
+        response.writeHead(405, { "content-type": "application/json" });
+        response.end(
+          JSON.stringify({ error: "Stateless MCP server: only POST /mcp is supported" })
+        );
+        return;
+      }
+      let raw = "";
+      request.on("data", (chunk) => {
+        raw += chunk;
+      });
+      request.on("end", () => {
+        void (async () => {
+          let body;
+          try {
+            body = JSON.parse(raw);
+          } catch {
+            response.writeHead(400, { "content-type": "application/json" });
+            response.end(JSON.stringify({ error: "Request body is not valid JSON" }));
+            return;
+          }
+          const server = buildMemoryMcpServer(store, agent);
+          const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: void 0
+            // stateless
+          });
+          response.on("close", () => {
+            void transport.close();
+            void server.close();
+          });
+          await server.connect(transport);
+          await transport.handleRequest(request, response, body);
+        })();
+      });
+    })();
+  });
+  await new Promise((resolve) => {
+    httpServer.listen(port, "127.0.0.1", resolve);
+  });
+  return httpServer;
+}
+
+// src/cli/memory-serve.ts
+function registerMemoryCommand(program2) {
+  const memory = program2.command("memory").description("Memory server commands");
+  memory.command("serve").option("--agent <name>", "agent name to scope memory to (or run from an agent dir)").option("--backend <backend>", "file | postgres", "file").option("--url <url>", "postgres connection string (or set DATABASE_URL)").option("--http", "serve over streamable HTTP instead of stdio").option("--port <port>", "HTTP port (with --http)", "8787").description("Serve agent memory over the Model Context Protocol").action(
+    async (options) => {
+      if (options.backend !== "file" && options.backend !== "postgres") {
+        throw new Error(`Unknown backend "${options.backend}" \u2014 use "file" or "postgres".`);
+      }
+      let agent = options.agent;
+      let rootDir = process.cwd();
+      if (!agent) {
+        const manifestHere = path11.join(process.cwd(), "kohala.json");
+        if (fs10.existsSync(manifestHere)) {
+          agent = loadManifest(process.cwd()).name;
+          rootDir = path11.dirname(process.cwd());
+        } else {
+          throw new Error(
+            "Pass --agent <name>, or run this from inside an agent directory (one containing kohala.json)."
+          );
+        }
+      }
+      const store = await createMemoryStore({
+        backend: options.backend,
+        agent,
+        rootDir,
+        url: options.url ?? process.env.DATABASE_URL
+      });
+      if (options.http) {
+        const port = Number(options.port);
+        await serveHttp(store, agent, port);
+        console.error(
+          pc6.green(`MCP memory server for "${agent}" listening on http://127.0.0.1:${port}/mcp`)
+        );
+        console.error(pc6.dim(`backend=${options.backend} \u2014 ctrl-c to stop`));
+      } else {
+        console.error(
+          pc6.dim(`MCP memory server for "${agent}" on stdio (backend=${options.backend})`)
+        );
+        await serveStdio(store, agent);
+      }
+    }
+  );
+}
+
+// src/cli/login.ts
+import readline from "readline";
+import pc7 from "picocolors";
+
+// src/deploy/credentials.ts
+import fs11 from "fs";
+import os from "os";
+import path12 from "path";
+function credentialsPath() {
+  return path12.join(os.homedir(), ".kohala", "credentials.json");
+}
+function saveApiKey(apiKey) {
+  if (!apiKey.startsWith("pk_")) {
+    throw new Error('Kohala API keys start with "pk_". Check the key and try again.');
+  }
+  const filePath = credentialsPath();
+  fs11.mkdirSync(path12.dirname(filePath), { recursive: true });
+  const payload = { apiKey };
+  fs11.writeFileSync(filePath, JSON.stringify(payload, null, 2), { encoding: "utf8", mode: 384 });
+  fs11.chmodSync(filePath, 384);
+  return filePath;
+}
+function resolveApiKey(env = process.env) {
+  if (env.KOHALA_API_KEY) return env.KOHALA_API_KEY;
+  const filePath = credentialsPath();
+  if (!fs11.existsSync(filePath)) return null;
+  try {
+    const parsed = JSON.parse(fs11.readFileSync(filePath, "utf8"));
+    return parsed.apiKey ?? null;
+  } catch {
+    throw new Error(
+      `${filePath} is corrupted \u2014 delete it and run "kohala login" again.`
+    );
+  }
+}
+
+// src/cli/login.ts
+function registerLoginCommand(program2) {
+  program2.command("login").option("--api-key <key>", "provide the key non-interactively").description("Save your Kohala API key for `kohala deploy`").action(async (options) => {
+    let apiKey = options.apiKey;
+    if (!apiKey) {
+      apiKey = await promptHidden(
+        "Paste your Kohala API key (starts with pk_, from kohala.ai account settings): "
+      );
+    }
+    if (!apiKey) {
+      throw new Error("No API key provided.");
+    }
+    const savedTo = saveApiKey(apiKey.trim());
+    console.log(pc7.green(`API key saved to ${savedTo} (permissions 600).`));
+    console.log(pc7.dim("Note: the KOHALA_API_KEY environment variable overrides this file."));
+  });
+}
+function promptHidden(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    const stdin = process.stdin;
+    process.stderr.write(question);
+    if (stdin.isTTY && stdin.setRawMode) {
+      stdin.setRawMode(true);
+      let value = "";
+      const onData = (chunk) => {
+        const char = chunk.toString("utf8");
+        if (char === "\n" || char === "\r" || char === "") {
+          stdin.setRawMode?.(false);
+          stdin.off("data", onData);
+          rl.close();
+          process.stderr.write("\n");
+          resolve(value);
+        } else if (char === "") {
+          stdin.setRawMode?.(false);
+          rl.close();
+          process.exit(130);
+        } else if (char === "\x7F") {
+          value = value.slice(0, -1);
+        } else {
+          value += char;
+        }
+      };
+      stdin.on("data", onData);
+    } else {
+      rl.question("", (answer) => {
+        rl.close();
+        resolve(answer);
+      });
+    }
+  });
+}
+
+// src/cli/deploy.ts
+import path14 from "path";
+import pc8 from "picocolors";
+
+// src/deploy/client.ts
+import fs12 from "fs";
+import path13 from "path";
+var DEFAULT_BASE_URL = "https://kohala.ai";
+function buildDeployPlan(manifest, agentDir) {
+  const skills = Object.entries(manifest.skills).map(([name, scriptFilename]) => {
+    const scriptPath = path13.join(agentDir, "skills", scriptFilename);
+    if (!fs12.existsSync(scriptPath)) {
+      throw new Error(
+        `Skill "${name}" points at ${scriptFilename}, but ${scriptPath} does not exist.`
+      );
+    }
+    return {
+      name,
+      scriptFilename,
+      description: `Skill "${name}" of agent "${manifest.name}"`,
+      scriptContent: fs12.readFileSync(scriptPath, "utf8")
+    };
+  });
+  return {
+    agent: {
+      name: manifest.name,
+      charter: manifest.charter,
+      toolAllowlist: manifest.toolAllowlist,
+      runtimeMode: manifest.runtimeMode,
+      ...manifest.schedule ? { schedule: manifest.schedule } : {}
+    },
+    skills,
+    quota: {
+      perRunTokens: manifest.caps.perRunTokens,
+      perDayTokens: manifest.caps.perDayTokens,
+      ...manifest.caps.billingTokens !== void 0 ? { billingTokens: manifest.caps.billingTokens } : {},
+      ...manifest.caps.billingPeriod !== void 0 ? { billingPeriod: manifest.caps.billingPeriod } : {}
+    }
+  };
+}
+var DeployError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "DeployError";
+  }
+  status;
+};
+var KohalaClient = class {
+  constructor(apiKey, baseUrl = DEFAULT_BASE_URL) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+  }
+  apiKey;
+  baseUrl;
+  async request(method, apiPath, body) {
+    const response = await fetch(`${this.baseUrl}${apiPath}`, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.apiKey}`
+      },
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+    });
+    if (response.status === 401) {
+      throw new DeployError(
+        401,
+        "401 Unauthorized: your API key was rejected. Check KOHALA_API_KEY or re-run `kohala login` with a fresh pk_ key from your Kohala account settings."
+      );
+    }
+    if (response.status === 403) {
+      throw new DeployError(
+        403,
+        "403 Forbidden: your plan does not allow this operation. Check your plan at https://kohala.ai or contact support."
+      );
+    }
+    if (!response.ok) {
+      const text2 = await response.text();
+      throw new DeployError(
+        response.status,
+        `Kohala API error ${response.status} on ${method} ${apiPath}: ${text2.slice(0, 500)}`
+      );
+    }
+    const text = await response.text();
+    return text ? JSON.parse(text) : null;
+  }
+  /** Step 1: create or update the agent (idempotent on name). */
+  async upsertAgent(payload) {
+    const data = await this.request("POST", "/api/v1/agents", payload);
+    const id = data.id ?? data.agentId;
+    if (!id) {
+      throw new DeployError(500, "Platform response did not include an agent id");
+    }
+    return { id, created: data.created ?? false };
+  }
+  /** Step 2: upload one skill (script content inline). */
+  async upsertSkill(agentId, payload) {
+    await this.request("POST", `/api/v1/agents/${agentId}/skills`, payload);
+  }
+  /** Step 3: set the token caps. */
+  async setQuota(agentId, payload) {
+    await this.request("PUT", `/api/v1/agents/${agentId}/quota`, payload);
+  }
+  /** Optional step 4 (--run): trigger a manual run and return its link. */
+  async triggerManualRun(agentId) {
+    const data = await this.request("POST", `/api/v1/agents/${agentId}/agent-runs/manual`);
+    return data.runUrl ?? data.url ?? `${this.baseUrl}/agents/${agentId}/runs/${data.id ?? ""}`;
+  }
+};
+
+// src/cli/deploy.ts
+function registerDeployCommand(program2) {
+  program2.command("deploy").argument("<agent>", "agent directory (containing kohala.json)").option("--dry-run", "print the payloads without sending anything").option("--base-url <url>", "API base URL", DEFAULT_BASE_URL).option("--run", "trigger a manual run after deploying").description("Deploy an agent to kohala.ai (idempotent on agent name)").action(
+    async (agent, options) => {
+      const agentDir = path14.resolve(process.cwd(), agent);
+      const manifest = loadManifest(agentDir);
+      const plan = buildDeployPlan(manifest, agentDir);
+      if (options.dryRun) {
+        console.log(pc8.cyan("Dry run \u2014 nothing will be sent. Deploy plan:"));
+        console.log("");
+        console.log(pc8.bold("1. POST /api/v1/agents (idempotent on name)"));
+        console.log(JSON.stringify(plan.agent, null, 2));
+        for (const skill of plan.skills) {
+          console.log("");
+          console.log(pc8.bold(`2. POST /api/v1/agents/:id/skills \u2014 "${skill.name}"`));
+          console.log(
+            JSON.stringify(
+              { ...skill, scriptContent: `<${Buffer.byteLength(skill.scriptContent)} bytes of ${skill.scriptFilename}>` },
+              null,
+              2
+            )
+          );
+        }
+        console.log("");
+        console.log(pc8.bold("3. PUT /api/v1/agents/:id/quota"));
+        console.log(JSON.stringify(plan.quota, null, 2));
+        if (options.run) {
+          console.log("");
+          console.log(pc8.bold("4. POST /api/v1/agents/:id/agent-runs/manual"));
+        }
+        return;
+      }
+      const apiKey = resolveApiKey();
+      if (!apiKey) {
+        throw new Error(
+          "No API key configured. Run `kohala login` (or set KOHALA_API_KEY) first. Keys come from your kohala.ai account settings."
+        );
+      }
+      const client = new KohalaClient(apiKey, options.baseUrl);
+      console.log(pc8.cyan(`Deploying "${manifest.name}" to ${options.baseUrl} ...`));
+      const upserted = await client.upsertAgent(plan.agent);
+      console.log(
+        pc8.green(`  \u2714 agent ${upserted.created ? "created" : "updated"} (id ${upserted.id})`)
+      );
+      for (const skill of plan.skills) {
+        await client.upsertSkill(upserted.id, skill);
+        console.log(pc8.green(`  \u2714 skill "${skill.name}" uploaded (${skill.scriptFilename})`));
+      }
+      await client.setQuota(upserted.id, plan.quota);
+      console.log(
+        pc8.green(
+          `  \u2714 quota set (perRun=${plan.quota.perRunTokens}, perDay=${plan.quota.perDayTokens})`
+        )
+      );
+      if (options.run) {
+        const runUrl = await client.triggerManualRun(upserted.id);
+        console.log(pc8.green(`  \u2714 manual run triggered: ${runUrl}`));
+      }
+      console.log("");
+      console.log(pc8.green(`Deployed. Deploys are additive \u2014 nothing was deleted remotely.`));
+    }
+  );
+}
+
+// src/cli/doctor.ts
+import pc9 from "picocolors";
+function registerDoctorCommand(program2) {
+  program2.command("doctor").description("Check your environment: Node, Python, LLM keys, API key, DATABASE_URL").action(async () => {
+    const ok = (label, detail) => console.log(`${pc9.green("\u2714")} ${label} ${pc9.dim(detail)}`);
+    const warn = (label, detail) => console.log(`${pc9.yellow("\u2022")} ${label} ${pc9.dim(detail)}`);
+    const nodeMajor = Number(process.versions.node.split(".")[0]);
+    if (nodeMajor >= 20) {
+      ok(`node ${process.versions.node}`, "(>= 20 required)");
+    } else {
+      console.log(
+        `${pc9.red("\u2718")} node ${process.versions.node} \u2014 the devkit requires Node 20 or newer.`
+      );
+    }
+    try {
+      const python = await findPython();
+      ok(`python (${python})`, "wrap-mode skills can run");
+    } catch {
+      warn("python 3 not found", "wrap-mode `kohala run --local` will not work until installed");
+    }
+    const provider = detectLlmProvider();
+    if (provider) {
+      ok(`LLM key (${provider})`, "llm.complete and llm mode available");
+    } else {
+      warn(
+        "no ANTHROPIC_API_KEY / GEMINI_API_KEY",
+        "llm.complete and llm-mode runs will fail with NO_LLM_KEY"
+      );
+    }
+    const apiKey = resolveApiKey();
+    if (apiKey) {
+      const source = process.env.KOHALA_API_KEY ? "KOHALA_API_KEY env" : credentialsPath();
+      ok("Kohala API key", `from ${source} \u2014 kohala deploy ready`);
+    } else {
+      warn("no Kohala API key", "run `kohala login` before `kohala deploy` (local dev needs no account)");
+    }
+    if (process.env.DATABASE_URL) {
+      ok("DATABASE_URL set", "postgres memory backend available");
+    } else {
+      warn("DATABASE_URL not set", "memory uses the file backend (that is the default anyway)");
+    }
+    console.log("");
+    console.log(pc9.dim("Everything local works without an account \u2014 deploy is the only step that needs one."));
+  });
+}
+
+// src/cli/index.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../../package.json");
+var program = new Command();
+program.name("kohala").description(
+  "Kohala Devkit \u2014 build and run agents entirely on your own machine, then push the same agent to Kohala when you want it hosted."
+).version(version);
+registerInitCommand(program);
+registerValidateCommand(program);
+registerRunCommand(program);
+registerTraceCommand(program);
+registerMemoryCommand(program);
+registerLoginCommand(program);
+registerDeployCommand(program);
+registerDoctorCommand(program);
+program.parseAsync(process.argv).catch((error) => {
+  console.error(pc10.red(`
+${error.message}`));
+  process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map