starcite 0.0.6 → 0.0.8

package/dist/index.js

@@ -1,114 +1,30 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import {
-  Starcite,
-  StarciteApiError,
-  StarciteIdentity
-} from "@starcite/sdk";
-import { Command, InvalidArgumentError } from "commander";
-import { createConsola } from "consola";
-import { z as z2 } from "zod";
+import { StarciteApiError } from "@starcite/sdk";
 
-// package.json
-var package_default = {
-  name: "starcite",
-  version: "0.0.6",
-  description: "CLI for Starcite",
-  license: "Apache-2.0",
-  homepage: "https://starcite.ai",
-  repository: {
-    type: "git",
-    url: "https://github.com/fastpaca/starcite-clients.git",
-    directory: "packages/starcite-cli"
-  },
-  bugs: {
-    url: "https://github.com/fastpaca/starcite-clients/issues"
-  },
-  keywords: [
-    "starcite",
-    "ai",
-    "sessions",
-    "event-log",
-    "cli"
-  ],
-  type: "module",
-  bin: {
-    starcite: "./dist/index.js"
-  },
-  files: [
-    "dist"
-  ],
-  scripts: {
-    clean: "rm -rf dist",
-    build: "tsup",
-    dev: "bun run src/index.ts",
-    compile: "bun run --cwd ../typescript-sdk build && bun build --compile src/index.ts --outfile dist/starcite",
-    test: "vitest run && bun run test:dist",
-    "test:live": "vitest run test/live.api.integration.test.ts",
-    typecheck: "tsc -p tsconfig.json --noEmit",
-    prepublishOnly: "bun run clean && bun run build",
-    "publish:dry": "bun publish --dry-run --access public",
-    "test:dist": "bun run --cwd ../typescript-sdk build && bun run clean && bun run build && node dist/index.js --help > /dev/null",
-    lint: "ultracite check src test package.json tsconfig.json tsup.config.ts vitest.config.ts README.md",
-    format: "ultracite fix src test package.json tsconfig.json tsup.config.ts vitest.config.ts README.md",
-    check: "bun run lint && bun run typecheck && bun run test"
-  },
-  dependencies: {
-    "@clack/prompts": "^1.0.1",
-    "@starcite/sdk": "^0.0.6",
-    commander: "^13.1.0",
-    conf: "^15.1.0",
-    consola: "^3.4.2",
-    cosmiconfig: "^9.0.0",
-    "proper-lockfile": "^4.1.2",
-    toml: "^3.0.0",
-    zod: "^3.25.76"
-  },
-  devDependencies: {
-    "@types/node": "^22.15.30",
-    "@types/proper-lockfile": "^4.1.4",
-    tsup: "^8.5.0",
-    typescript: "^5.8.3",
-    vitest: "^2.1.9"
-  }
-};
+// src/runtime.ts
+import { Starcite } from "@starcite/sdk";
+import arg from "arg";
 
-// src/store.ts
-import { randomUUID } from "crypto";
-import { mkdir, writeFile } from "fs/promises";
-import { homedir, hostname } from "os";
+// src/config.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
 import { join, resolve } from "path";
 import Conf from "conf";
-import { cosmiconfig, defaultLoaders } from "cosmiconfig";
-import { lock } from "proper-lockfile";
 import { parse as parseToml } from "toml";
 import { z } from "zod";
 var DEFAULT_CONFIG_DIRECTORY_NAME = ".starcite";
 var CONFIG_JSON_FILENAME = "config.json";
 var CONFIG_TOML_FILENAME = "config.toml";
 var CREDENTIALS_FILENAME = "credentials";
-var IDENTITY_FILENAME = "identity";
-var STATE_FILENAME = "state";
-var STATE_LOCK_FILENAME = ".state.lock";
 var TILDE_PREFIX_REGEX = /^~(?=\/|$)/;
 var ConfigFileSchema = z.object({
   baseUrl: z.string().optional(),
   base_url: z.string().optional(),
-  producerId: z.string().optional(),
-  producer_id: z.string().optional(),
   apiKey: z.string().optional(),
   api_key: z.string().optional()
 }).passthrough();
-var IdentityFileSchema = z.object({
-  producerId: z.string().trim().min(1),
-  hostname: z.string().trim().min(1),
-  uuid: z.string().uuid(),
-  createdAt: z.string()
-});
-var StateFileSchema = z.object({
-  nextSeqByContext: z.record(z.number().int().positive()).default({})
-});
 var CredentialsFileSchema = z.object({
   apiKey: z.string().trim().min(1).optional()
 });
@@ -123,1064 +39,741 @@ function normalizeConfig(input) {
   }
   return {
     baseUrl: trimString(parsed.data.baseUrl ?? parsed.data.base_url),
-    producerId: trimString(parsed.data.producerId ?? parsed.data.producer_id),
     apiKey: trimString(parsed.data.apiKey ?? parsed.data.api_key)
   };
 }
 function defaultConfigDirectory() {
   const home = homedir();
-  if (home.trim().length > 0) {
-    return join(home, DEFAULT_CONFIG_DIRECTORY_NAME);
-  }
-  return resolve(DEFAULT_CONFIG_DIRECTORY_NAME);
+  return home.trim().length > 0 ? join(home, DEFAULT_CONFIG_DIRECTORY_NAME) : resolve(DEFAULT_CONFIG_DIRECTORY_NAME);
 }
 function resolveConfigDir(input) {
   const configured = trimString(input) ?? trimString(process.env.STARCITE_HOME);
   const withTilde = configured?.startsWith("~") ? configured.replace(TILDE_PREFIX_REGEX, homedir()) : configured;
   return resolve(withTilde ?? defaultConfigDirectory());
 }
-function buildSeqContextKey(baseUrl, sessionId, producerId) {
-  return `${baseUrl}::${sessionId}::${producerId}`;
-}
-var StarciteCliStore = class {
+var StarciteCliConfigStore = class {
   directory;
-  lockPath;
-  configExplorer = cosmiconfig("starcite", {
-    cache: false,
-    searchStrategy: "none",
-    searchPlaces: [CONFIG_JSON_FILENAME, CONFIG_TOML_FILENAME],
-    loaders: {
-      ...defaultLoaders,
-      ".toml": (_filepath, content) => parseToml(content)
-    }
-  });
-  identityStore;
   credentialsStore;
-  stateStore;
   constructor(directory) {
     this.directory = directory;
-    this.lockPath = join(directory, STATE_LOCK_FILENAME);
-    this.identityStore = new Conf({
-      cwd: directory,
-      clearInvalidConfig: true,
-      configName: IDENTITY_FILENAME,
-      fileExtension: "json"
-    });
     this.credentialsStore = new Conf({
       cwd: directory,
       clearInvalidConfig: true,
       configName: CREDENTIALS_FILENAME,
-      fileExtension: "json",
-      defaults: {}
-    });
-    this.stateStore = new Conf({
-      cwd: directory,
-      clearInvalidConfig: true,
-      configName: STATE_FILENAME,
-      fileExtension: "json",
-      defaults: { nextSeqByContext: {} }
+      fileExtension: "json"
     });
   }
   async readConfig() {
-    await this.ensureConfigDirectory();
-    const result = await this.configExplorer.search(this.directory);
-    if (!result) {
-      return {};
+    await this.ensureDirectory();
+    for (const filename of [CONFIG_JSON_FILENAME, CONFIG_TOML_FILENAME]) {
+      const parsed = await this.readConfigFile(filename);
+      if (parsed !== void 0) {
+        return normalizeConfig(parsed);
+      }
     }
-    return normalizeConfig(result.config);
+    return {};
   }
   async writeConfig(config) {
-    await this.ensureConfigDirectory();
+    await this.ensureDirectory();
     const normalized = normalizeConfig(config);
-    const serialized = {};
-    if (normalized.baseUrl) {
-      serialized.baseUrl = normalized.baseUrl;
-    }
-    if (normalized.producerId) {
-      serialized.producerId = normalized.producerId;
-    }
-    if (normalized.apiKey) {
-      serialized.apiKey = normalized.apiKey;
-    }
     await writeFile(
       join(this.directory, CONFIG_JSON_FILENAME),
-      `${JSON.stringify(serialized, null, 2)}
+      `${JSON.stringify(normalized, null, 2)}
 `,
       "utf8"
     );
   }
   async updateConfig(patch) {
-    const current = await this.readConfig();
-    const merged = normalizeConfig({
-      ...current,
+    const config = normalizeConfig({
+      ...await this.readConfig(),
       ...patch
     });
-    await this.writeConfig(merged);
-    return merged;
+    await this.writeConfig(config);
+    return config;
   }
   async readApiKey() {
     const fromEnv = trimString(process.env.STARCITE_API_KEY);
     if (fromEnv) {
       return fromEnv;
     }
-    const parsed = CredentialsFileSchema.safeParse(this.credentialsStore.store);
-    const fromCredentials = parsed.success ? trimString(parsed.data.apiKey) : void 0;
+    const fromCredentials = trimString(this.readCredentials().apiKey);
     if (fromCredentials) {
       return fromCredentials;
     }
-    const config = await this.readConfig();
-    return trimString(config.apiKey);
+    return trimString((await this.readConfig()).apiKey);
   }
   async saveApiKey(apiKey) {
-    await this.ensureConfigDirectory();
+    await this.ensureDirectory();
     const normalized = trimString(apiKey);
     if (!normalized) {
       throw new Error("API key cannot be empty");
     }
     this.credentialsStore.set("apiKey", normalized);
   }
-  async clearApiKey() {
-    await this.ensureConfigDirectory();
-    this.credentialsStore.delete("apiKey");
-  }
-  async resolveProducerId(explicitProducerId) {
-    const explicit = trimString(explicitProducerId);
-    if (explicit) {
-      return explicit;
-    }
-    const fromEnv = trimString(process.env.STARCITE_PRODUCER_ID);
-    if (fromEnv) {
-      return fromEnv;
-    }
-    const config = await this.readConfig();
-    const fromConfig = trimString(config.producerId);
-    if (fromConfig) {
-      return fromConfig;
-    }
-    const identity = await this.readOrCreateIdentity();
-    return identity.producerId;
-  }
-  async withStateLock(action) {
-    await this.ensureConfigDirectory();
-    const release = await lock(this.directory, {
-      lockfilePath: this.lockPath,
-      realpath: false,
-      retries: {
-        retries: 50,
-        minTimeout: 20,
-        maxTimeout: 60
-      }
-    });
+  async readConfigFile(filename) {
+    const path = join(this.directory, filename);
     try {
-      return await action();
-    } finally {
-      await release();
-    }
-  }
-  readNextSeq(contextKey) {
-    const state = this.readState();
-    return Promise.resolve(state.nextSeqByContext[contextKey] ?? 1);
-  }
-  bumpNextSeq(contextKey, usedSeq) {
-    const state = this.readState();
-    const nextSeqByContext = {
-      ...state.nextSeqByContext,
-      [contextKey]: Math.max(
-        state.nextSeqByContext[contextKey] ?? 1,
-        usedSeq + 1
-      )
-    };
-    this.stateStore.set("nextSeqByContext", nextSeqByContext);
-    return Promise.resolve();
-  }
-  readState() {
-    const parsed = StateFileSchema.safeParse(this.stateStore.store);
-    if (parsed.success) {
-      return parsed.data;
+      const content = await readFile(path, "utf8");
+      return filename.endsWith(".toml") ? parseToml(content) : JSON.parse(content);
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+        return void 0;
+      }
+      throw error;
     }
-    this.stateStore.clear();
-    return { nextSeqByContext: {} };
   }
-  readOrCreateIdentity() {
-    const parsed = IdentityFileSchema.safeParse(this.identityStore.store);
+  readCredentials() {
+    const parsed = CredentialsFileSchema.safeParse(this.credentialsStore.store);
     if (parsed.success) {
       return parsed.data;
     }
-    const host = hostname();
-    const uuid = randomUUID();
-    const identity = {
-      producerId: `cli:${host}:${uuid}`,
-      hostname: host,
-      uuid,
-      createdAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    this.identityStore.store = identity;
-    return identity;
+    this.credentialsStore.clear();
+    return {};
   }
-  async ensureConfigDirectory() {
+  async ensureDirectory() {
     await mkdir(this.directory, { recursive: true });
   }
 };
 
-// src/up.ts
-import { spawn } from "child_process";
-import { mkdir as mkdir2, stat, writeFile as writeFile2 } from "fs/promises";
-import { join as join2 } from "path";
+// src/store.ts
 import {
-  cancel as clackCancel,
-  confirm as clackConfirm,
-  password as clackPassword,
-  text as clackText,
-  isCancel
-} from "@clack/prompts";
-var DEFAULT_API_PORT = 45187;
-var DEFAULT_DB_PORT = 5433;
-var MIN_PORT = 1;
-var MAX_PORT = 65535;
-var RUNTIME_DIRECTORY_NAME = "runtime";
-var DEFAULT_COMPOSE_FILE = `services:
-  app:
-    image: \${STARCITE_IMAGE:-ghcr.io/fastpaca/starcite:latest}
-    depends_on:
-      db:
-        condition: service_healthy
-    environment:
-      SECRET_KEY_BASE: \${SECRET_KEY_BASE:-xuQnOFm6sH5Qdd7x4WJv5smuG2Xf2nG0BL8rJ4yX6HnKGeTjo6n8r5hQKsxNkZWz}
-      PHX_HOST: \${PHX_HOST:-localhost}
-      PORT: 4000
-      DATABASE_URL: \${DATABASE_URL:-ecto://postgres:postgres@db:5432/starcite_dev}
-      MIGRATE_ON_BOOT: \${MIGRATE_ON_BOOT:-true}
-      DNS_CLUSTER_QUERY: \${DNS_CLUSTER_QUERY:-}
-      DNS_CLUSTER_NODE_BASENAME: \${DNS_CLUSTER_NODE_BASENAME:-starcite}
-      DNS_POLL_INTERVAL_MS: \${DNS_POLL_INTERVAL_MS:-5000}
-    ports:
-      - "\${STARCITE_API_PORT:-45187}:4000"
-    restart: unless-stopped
-
-  db:
-    image: postgres:15
-    environment:
-      POSTGRES_DB: starcite_dev
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
-    healthcheck:
-      test: ["CMD", "pg_isready", "-U", "postgres"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-    ports:
-      - "\${STARCITE_DB_PORT:-5433}:5432"
-    volumes:
-      - db-data:/var/lib/postgresql/data
-    restart: unless-stopped
-
-volumes:
-  db-data:
-`;
-function parsePort(value, optionName) {
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed < MIN_PORT || parsed > MAX_PORT) {
-    throw new Error(
-      `${optionName} must be an integer between ${MIN_PORT} and ${MAX_PORT}`
-    );
-  }
-  return parsed;
+  WebStorageSessionStore
+} from "@starcite/sdk";
+import Conf2 from "conf";
+var STATE_FILENAME = "state";
+var TRAILING_SLASHES_REGEX = /\/+$/;
+var STORE_VERSION_KEY = "__starciteCliStoreVersion";
+var CURRENT_STORE_VERSION = "2";
+function buildSessionStoreContextKey(baseUrl, sessionId) {
+  return `${baseUrl}::${sessionId}`;
 }
-function baseUrlPort(baseUrl) {
-  try {
-    const parsed = new URL(baseUrl);
-    if (parsed.port) {
-      return parsePort(parsed.port, "base URL port");
-    }
-  } catch {
-    return DEFAULT_API_PORT;
+function normalizeStoreBaseUrl(baseUrl) {
+  if (baseUrl.length === 0) {
+    return "";
   }
-  return DEFAULT_API_PORT;
-}
-async function ensureSuccess(runCommand, command, args) {
-  const result = await runCommand(command, args);
-  return result.code === 0;
+  const normalized = baseUrl.replace(TRAILING_SLASHES_REGEX, "");
+  return normalized.endsWith("/v1") ? normalized : `${normalized}/v1`;
 }
-async function ensureDockerReady(logger, runCommand) {
-  const hasDocker = await ensureSuccess(runCommand, "docker", ["--version"]);
-  if (!hasDocker) {
-    logger.error("You don't have Docker installed, please install it.");
-    throw new Error("Docker is required to run this command.");
+var StarciteCliStore = class {
+  storage;
+  constructor(directory) {
+    this.storage = new Conf2({
+      cwd: directory,
+      clearInvalidConfig: true,
+      configName: STATE_FILENAME,
+      fileExtension: "json",
+      defaults: {}
+    });
+    this.resetOnStoreVersionMismatch();
   }
-  const hasDockerCompose = await ensureSuccess(runCommand, "docker", [
-    "compose",
-    "version"
-  ]);
-  if (!hasDockerCompose) {
-    logger.error(
-      "Docker Compose is not available. Install Docker Compose and retry."
-    );
-    throw new Error("Docker Compose is required to run this command.");
+  sessionStore(baseUrl) {
+    return new WebStorageSessionStore(this.storageAdapter(), {
+      keyForSession: (sessionId) => buildSessionStoreContextKey(normalizeStoreBaseUrl(baseUrl), sessionId)
+    });
   }
-  const daemonRunning = await ensureSuccess(runCommand, "docker", ["info"]);
-  if (!daemonRunning) {
-    logger.error("Docker is installed but the daemon is not running.");
-    throw new Error("Start Docker and retry.");
+  load(sessionId) {
+    return this.sessionStore("").load(sessionId);
   }
-}
-async function selectApiPort(baseUrl, options, prompt) {
-  if (options.port !== void 0) {
-    return options.port;
+  save(sessionId, state) {
+    this.sessionStore("").save(sessionId, state);
   }
-  const fallbackPort = baseUrlPort(baseUrl);
-  if (options.yes) {
-    return fallbackPort;
+  clear(sessionId) {
+    this.sessionStore("").clear?.(sessionId);
   }
-  while (true) {
-    const answer = await prompt.input(
-      "What port do you want it on?",
-      `${fallbackPort}`
-    );
-    try {
-      return parsePort(answer, "port");
-    } catch (error) {
-      if (error instanceof Error) {
+  clearSession(baseUrl, sessionId) {
+    this.sessionStore(baseUrl).clear?.(sessionId);
+  }
+  storageAdapter() {
+    return {
+      getItem: (key) => this.storage.get(key) ?? null,
+      setItem: (key, value) => {
+        this.storage.set(key, value);
+      },
+      removeItem: (key) => {
+        this.storage.delete(key);
       }
+    };
+  }
+  resetOnStoreVersionMismatch() {
+    const storedVersion = this.storage.get(STORE_VERSION_KEY);
+    if (storedVersion === CURRENT_STORE_VERSION) {
+      return;
     }
+    this.storage.clear();
+    this.storage.set(STORE_VERSION_KEY, CURRENT_STORE_VERSION);
   }
-}
-function runtimeDirectory(store) {
-  return join2(store.directory, RUNTIME_DIRECTORY_NAME);
-}
-async function runtimeDirectoryExists(store) {
-  try {
-    const result = await stat(runtimeDirectory(store));
-    return result.isDirectory();
-  } catch {
-    return false;
+};
+
+// src/runtime.ts
+var DEFAULT_API_PORT = 45187;
+var DEFAULT_TAIL_BATCH_SIZE = 256;
+var TRAILING_SLASHES_REGEX2 = /\/+$/;
+var CliUsageError = class extends Error {
+};
+var defaultLogger = {
+  info(message) {
+    console.log(message);
+  },
+  error(message) {
+    console.error(message);
   }
-}
-async function writeComposeFiles(store, options) {
-  const directory = runtimeDirectory(store);
-  await mkdir2(directory, { recursive: true });
-  await writeFile2(
-    join2(directory, "docker-compose.yml"),
-    DEFAULT_COMPOSE_FILE,
-    "utf8"
-  );
-  const envLines = [
-    `STARCITE_API_PORT=${options.apiPort}`,
-    `STARCITE_DB_PORT=${options.dbPort}`
-  ];
-  if (options.image?.trim()) {
-    envLines.push(`STARCITE_IMAGE=${options.image.trim()}`);
+};
+var defaultStdout = {
+  write(message) {
+    process.stdout.write(message);
   }
-  await writeFile2(join2(directory, ".env"), `${envLines.join("\n")}
-`, "utf8");
-  return directory;
+};
+function trimString2(value) {
+  const trimmed = value?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : void 0;
 }
-function parsePortOption(value, optionName) {
+function parseArgs(spec, argv, stopAtPositional = false) {
   try {
-    return parsePort(value, optionName);
+    return arg(spec, {
+      argv,
+      permissive: false,
+      stopAtPositional
+    });
   } catch (error) {
     if (error instanceof Error) {
-      throw new Error(error.message);
+      throw new CliUsageError(error.message);
     }
     throw error;
   }
 }
-async function runUpWizard(input) {
-  const { baseUrl, logger, options, prompt, runCommand, store } = input;
-  await ensureDockerReady(logger, runCommand);
-  const confirmed = options.yes ? true : await prompt.confirm(
-    "Are you sure you want to create the docker containers?",
-    true
-  );
-  if (!confirmed) {
-    logger.info("Cancelled.");
-    return;
-  }
-  const apiPort = await selectApiPort(baseUrl, options, prompt);
-  const dbPort = options.dbPort ?? DEFAULT_DB_PORT;
-  const composeDirectory = await writeComposeFiles(store, {
-    apiPort,
-    dbPort,
-    image: options.image
-  });
-  const result = await runCommand("docker", ["compose", "up", "-d"], {
-    cwd: composeDirectory
-  });
-  if (result.code !== 0) {
-    const message = result.stderr || result.stdout || "docker compose up failed";
-    throw new Error(message.trim());
-  }
-  logger.info(`Starcite is starting on http://localhost:${apiPort}`);
-  logger.info(`Compose files are in ${composeDirectory}`);
+function resolveConfiguredBaseUrl(config, options) {
+  return trimString2(options.baseUrl) ?? trimString2(process.env.STARCITE_BASE_URL) ?? trimString2(config.baseUrl) ?? `http://localhost:${DEFAULT_API_PORT}`;
 }
-async function runDownWizard(input) {
-  const { logger, options, prompt, runCommand, store } = input;
-  await ensureDockerReady(logger, runCommand);
-  const hasRuntimeDirectory = await runtimeDirectoryExists(store);
-  if (!hasRuntimeDirectory) {
-    logger.info(
-      `No Starcite runtime found at ${runtimeDirectory(
-        store
-      )}. Nothing to tear down.`
-    );
-    return;
-  }
-  const removeVolumes = options.volumes ?? true;
-  const confirmed = options.yes ? true : await prompt.confirm(
-    removeVolumes ? "Are you sure you want to stop and delete Starcite containers and volumes?" : "Are you sure you want to stop Starcite containers?",
-    false
-  );
-  if (!confirmed) {
-    logger.info("Cancelled.");
-    return;
-  }
-  const args = ["compose", "down", "--remove-orphans"];
-  if (removeVolumes) {
-    args.push("-v");
-  }
-  const result = await runCommand("docker", args, {
-    cwd: runtimeDirectory(store)
-  });
-  if (result.code !== 0) {
-    const message = result.stderr || result.stdout || "docker compose down failed";
-    throw new Error(message.trim());
-  }
-  logger.info("Starcite containers stopped.");
-  if (removeVolumes) {
-    logger.info("Starcite volumes removed.");
-  }
-}
-function createDefaultPrompt() {
-  const assertInteractive = () => {
-    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
-      throw new Error(
-        "Interactive mode requires a TTY. Re-run with explicit options (for example: --yes, --endpoint, --api-key)."
-      );
-    }
-  };
-  return {
-    async confirm(message, defaultValue = true) {
-      assertInteractive();
-      const answer = await clackConfirm({
-        message,
-        initialValue: defaultValue,
-        input: process.stdin,
-        output: process.stdout
-      });
-      if (isCancel(answer)) {
-        clackCancel("Cancelled.");
-        return false;
-      }
-      return answer;
-    },
-    async input(message, defaultValue = "") {
-      assertInteractive();
-      const answer = await clackText({
-        message,
-        defaultValue,
-        placeholder: defaultValue || void 0,
-        input: process.stdin,
-        output: process.stdout
-      });
-      if (isCancel(answer)) {
-        clackCancel("Cancelled.");
-        throw new Error("Cancelled.");
-      }
-      const normalized = answer.trim();
-      return normalized || defaultValue;
-    },
-    async password(message) {
-      assertInteractive();
-      const answer = await clackPassword({
-        message,
-        input: process.stdin,
-        output: process.stdout
-      });
-      if (isCancel(answer)) {
-        clackCancel("Cancelled.");
-        throw new Error("Cancelled.");
-      }
-      return answer.trim();
-    }
-  };
-}
-var defaultCommandRunner = (command, args, options) => new Promise((resolve2) => {
-  const child = spawn(command, args, {
-    cwd: options?.cwd,
-    stdio: ["ignore", "pipe", "pipe"]
-  });
-  let stdout = "";
-  let stderr = "";
-  child.stdout?.on("data", (chunk) => {
-    stdout += chunk.toString();
-  });
-  child.stderr?.on("data", (chunk) => {
-    stderr += chunk.toString();
-  });
-  child.on("error", (error) => {
-    const message = error.message || "command failed to start";
-    resolve2({ code: 127, stdout, stderr: `${stderr}${message}` });
-  });
-  child.on("close", (code) => {
-    resolve2({ code: code ?? 1, stdout, stderr });
-  });
-});
-
-// src/cli.ts
-var defaultLogger = createConsola();
-var cliVersion = package_default.version;
-var nonNegativeIntegerSchema = z2.coerce.number().int().nonnegative();
-var positiveIntegerSchema = z2.coerce.number().int().positive();
-var jsonObjectSchema = z2.record(z2.unknown());
-var GlobalOptionsSchema = z2.object({
-  baseUrl: z2.string().optional(),
-  configDir: z2.string().optional(),
-  token: z2.string().optional(),
-  json: z2.boolean().optional().default(false)
-});
-var TRAILING_SLASHES_REGEX = /\/+$/;
-var DEFAULT_TAIL_BATCH_SIZE = 256;
-var DEFAULT_CREATE_AGENT_ID = "starcite-cli";
 function parseNonNegativeInteger(value, optionName) {
-  const parsed = nonNegativeIntegerSchema.safeParse(value);
-  if (!parsed.success) {
-    throw new InvalidArgumentError(
-      `${optionName} must be a non-negative integer`
-    );
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new CliUsageError(`${optionName} must be a non-negative integer`);
   }
-  return parsed.data;
+  return parsed;
 }
 function parsePositiveInteger(value, optionName) {
-  const parsed = positiveIntegerSchema.safeParse(value);
-  if (!parsed.success) {
-    throw new InvalidArgumentError(`${optionName} must be a positive integer`);
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new CliUsageError(`${optionName} must be a positive integer`);
   }
-  return parsed.data;
-}
-function parsePort2(value, optionName) {
-  return parsePortOption(value, optionName);
+  return parsed;
 }
 function parseEndpoint(value, optionName) {
   const endpoint = trimString2(value);
   if (!endpoint) {
-    throw new InvalidArgumentError(`${optionName} cannot be empty`);
+    throw new CliUsageError(`${optionName} cannot be empty`);
   }
   let parsed;
   try {
     parsed = new URL(endpoint);
   } catch {
-    throw new InvalidArgumentError(`${optionName} must be a valid URL`);
+    throw new CliUsageError(`${optionName} must be a valid URL`);
   }
   if (!(parsed.protocol === "http:" || parsed.protocol === "https:")) {
-    throw new InvalidArgumentError(
-      `${optionName} must use http:// or https://`
-    );
+    throw new CliUsageError(`${optionName} must use http:// or https://`);
   }
-  return endpoint.replace(TRAILING_SLASHES_REGEX, "");
+  return endpoint.replace(TRAILING_SLASHES_REGEX2, "");
 }
 function parseConfigSetKey(value) {
   const normalized = value.trim().toLowerCase();
-  if (["endpoint", "base-url", "base_url"].includes(normalized)) {
+  if (normalized === "endpoint" || normalized === "base-url") {
     return "endpoint";
   }
-  if (["producer-id", "producer_id"].includes(normalized)) {
-    return "producer-id";
-  }
-  if (["api-key", "api_key"].includes(normalized)) {
+  if (normalized === "api-key") {
     return "api-key";
   }
-  throw new InvalidArgumentError(
-    "config key must be one of: endpoint, producer-id, api-key"
-  );
+  throw new CliUsageError("config key must be one of: endpoint, api-key");
 }
 function parseJsonObject(value, optionName) {
   let parsed;
   try {
     parsed = JSON.parse(value);
   } catch {
-    throw new InvalidArgumentError(`${optionName} must be valid JSON`);
+    throw new CliUsageError(`${optionName} must be valid JSON`);
   }
-  const result = jsonObjectSchema.safeParse(parsed);
-  if (!result.success) {
-    throw new InvalidArgumentError(`${optionName} must be a JSON object`);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new CliUsageError(`${optionName} must be a JSON object`);
   }
-  return result.data;
+  return parsed;
 }
 function parseSessionMetadataFilters(value) {
-  const parsed = parseJsonObject(value, "--metadata");
   const filters = {};
-  for (const [key, rawValue] of Object.entries(parsed)) {
+  for (const [key, rawValue] of Object.entries(
+    parseJsonObject(value, "--metadata")
+  )) {
     if (key.trim().length === 0) {
-      throw new InvalidArgumentError("--metadata keys must be non-empty");
+      throw new CliUsageError("--metadata keys must be non-empty");
     }
     if (typeof rawValue !== "string") {
-      throw new InvalidArgumentError("--metadata values must be strings");
+      throw new CliUsageError("--metadata values must be strings");
     }
     filters[key] = rawValue;
   }
   return filters;
 }
-function getGlobalOptions(command) {
-  const parsed = GlobalOptionsSchema.safeParse(command.optsWithGlobals());
-  if (!parsed.success) {
-    const issue = parsed.error.issues[0]?.message ?? "invalid global options";
-    throw new InvalidArgumentError(`Failed to parse global options: ${issue}`);
-  }
-  return parsed.data;
-}
-function trimString2(value) {
-  const trimmed = value?.trim();
-  return trimmed && trimmed.length > 0 ? trimmed : void 0;
-}
-function resolveBaseUrl(config, options) {
-  const defaultBaseUrl = `http://localhost:${DEFAULT_API_PORT}`;
-  return trimString2(options.baseUrl) ?? trimString2(process.env.STARCITE_BASE_URL) ?? trimString2(config.baseUrl) ?? defaultBaseUrl;
-}
-async function resolveGlobalOptions(command) {
-  const options = getGlobalOptions(command);
-  const configDir = resolveConfigDir(options.configDir);
-  const store = new StarciteCliStore(configDir);
-  const config = await store.readConfig();
-  const apiKey = trimString2(options.token) ?? await store.readApiKey();
-  return {
-    baseUrl: resolveBaseUrl(config, options),
-    apiKey,
-    json: options.json,
-    store
-  };
-}
-function formatTailEvent(event) {
-  const actorLabel = event.actor.startsWith("agent:") ? event.actor.slice("agent:".length) : event.actor;
-  const maybeText = event.payload?.text;
-  if (typeof maybeText === "string") {
-    return `[${actorLabel}] ${maybeText}`;
-  }
-  return `[${actorLabel}] ${JSON.stringify(event.payload)}`;
-}
-function parseJwtClaims(token) {
-  const parts = token.split(".");
-  if (parts.length < 2) {
-    return void 0;
+var CliRuntime = class {
+  logger;
+  stdout;
+  createClient;
+  constructor(deps = {}) {
+    this.logger = deps.logger ?? defaultLogger;
+    this.stdout = deps.stdout ?? defaultStdout;
+    this.createClient = deps.createClient;
   }
-  const payload = parts[1];
-  if (!payload) {
-    return void 0;
+  async resolveGlobalOptions(options) {
+    const config = new StarciteCliConfigStore(
+      resolveConfigDir(options.configDir)
+    );
+    const store = new StarciteCliStore(config.directory);
+    const baseUrl = resolveConfiguredBaseUrl(
+      await config.readConfig(),
+      options
+    );
+    const apiKey = trimString2(options.token) ?? await config.readApiKey();
+    const client = this.createClient?.(baseUrl, apiKey, store) ?? new Starcite({
+      baseUrl,
+      apiKey,
+      store: store.sessionStore(baseUrl)
+    });
+    return {
+      baseUrl,
+      json: options.json,
+      config,
+      store,
+      client
+    };
   }
-  try {
-    const decoded = Buffer.from(payload, "base64url").toString("utf8");
-    const parsed = JSON.parse(decoded);
-    return typeof parsed === "object" && parsed !== null ? parsed : void 0;
-  } catch {
-    return void 0;
+  writeJsonOutput(value, pretty = false) {
+    const serialized = JSON.stringify(value, null, pretty ? 2 : void 0);
+    if (serialized === void 0) {
+      throw new Error("Failed to serialize JSON output");
+    }
+    this.stdout.write(`${serialized}
+`);
   }
-}
-function tokenTenantId(token) {
-  if (!token) {
-    return void 0;
+  formatTailEvent(event) {
+    const actor = event.actor.startsWith("agent:") ? event.actor.slice("agent:".length) : event.actor;
+    const text = event.payload?.text;
+    return typeof text === "string" ? `[${actor}] ${text}` : `[${actor}] ${JSON.stringify(event.payload)}`;
   }
-  const claims = parseJwtClaims(token);
-  const tenantId = claims?.tenant_id;
-  if (typeof tenantId !== "string") {
-    return void 0;
+};
+
+// src/commands/append.ts
+var DEFAULT_CREATE_AGENT_ID = "starcite-cli";
+function resolveAppendIdentity(selection, client) {
+  if (!selection) {
+    return client.agent({ id: DEFAULT_CREATE_AGENT_ID });
+  }
+  return selection.type === "agent" ? client.agent({ id: selection.id }) : client.user({ id: selection.id });
+}
+async function runAppendCommand(args, globalOptions, runtime) {
+  const parsed = parseArgs(
+    {
+      "--agent": String,
+      "--user": String,
+      "--text": String,
+      "--type": String,
+      "--source": String,
+      "--payload": String,
+      "--metadata": String,
+      "--refs": String,
+      "--idempotency-key": String,
+      "--expected-seq": String
+    },
+    args
+  );
+  const sessionId = `${parsed._[0] ?? ""}`;
+  if (!sessionId) {
+    throw new CliUsageError("append requires <sessionId>");
+  }
+  const agent = trimString2(parsed["--agent"]);
+  const user = trimString2(parsed["--user"]);
+  const text = trimString2(parsed["--text"]);
+  const payload = parsed["--payload"] ? parseJsonObject(parsed["--payload"], "--payload") : void 0;
+  if (agent && user) {
+    throw new CliUsageError("Choose either --agent or --user, not both");
+  }
+  if (text && payload) {
+    throw new CliUsageError("Choose either --text or --payload, not both");
+  }
+  if (!(text || payload)) {
+    throw new CliUsageError("append requires either --text or --payload");
+  }
+  let identity;
+  if (agent) {
+    identity = { type: "agent", id: agent };
+  } else if (user) {
+    identity = { type: "user", id: user };
+  }
+  const resolved = await runtime.resolveGlobalOptions(globalOptions);
+  const session = await resolved.client.session({
+    identity: resolveAppendIdentity(identity, resolved.client),
+    id: sessionId
+  });
+  const response = await session.append({
+    type: parsed["--type"] ?? "content",
+    payload: payload ?? { text },
+    source: parsed["--source"],
+    metadata: parsed["--metadata"] ? parseJsonObject(parsed["--metadata"], "--metadata") : void 0,
+    refs: parsed["--refs"] ? parseJsonObject(parsed["--refs"], "--refs") : void 0,
+    idempotencyKey: parsed["--idempotency-key"],
+    expectedSeq: parsed["--expected-seq"] ? parseNonNegativeInteger(parsed["--expected-seq"], "--expected-seq") : void 0
+  });
+  if (resolved.json) {
+    runtime.writeJsonOutput(response, true);
+    return;
   }
-  const trimmed = tenantId.trim();
-  return trimmed.length > 0 ? trimmed : void 0;
+  runtime.logger.info(`seq=${response.seq} deduped=${response.deduped}`);
 }
-function tokenScopes(token) {
-  const claims = parseJwtClaims(token);
-  if (!claims) {
-    return /* @__PURE__ */ new Set();
-  }
-  const scopes = /* @__PURE__ */ new Set();
-  const scopeClaim = claims.scope;
-  if (typeof scopeClaim === "string") {
-    for (const scope of scopeClaim.split(" ")) {
-      if (scope.length > 0) {
-        scopes.add(scope);
-      }
+
+// src/commands/config.ts
+async function runConfigCommand(args, globalOptions, runtime) {
+  const action = args[0];
+  const config = new StarciteCliConfigStore(
+    resolveConfigDir(globalOptions.configDir)
+  );
+  if (action === "set") {
+    const key = args[1];
+    const value = args[2];
+    if (!(key && value)) {
+      throw new CliUsageError("config set requires <key> and <value>");
     }
-  }
-  const scopesClaim = claims.scopes;
-  if (Array.isArray(scopesClaim)) {
-    for (const scope of scopesClaim) {
-      if (typeof scope === "string" && scope.length > 0) {
-        scopes.add(scope);
-      }
+    if (parseConfigSetKey(key) === "endpoint") {
+      const endpoint = parseEndpoint(value, "endpoint");
+      await config.updateConfig({ baseUrl: endpoint });
+      runtime.logger.info(`Endpoint set to ${endpoint}`);
+      return;
     }
+    await config.saveApiKey(value);
+    await config.updateConfig({ apiKey: void 0 });
+    runtime.logger.info("API key saved.");
+    return;
   }
-  return scopes;
-}
-function shouldAutoIssueSessionToken(token) {
-  const scopes = tokenScopes(token);
-  return scopes.has("auth:issue");
-}
-function resolveAppendMode(options) {
-  const highLevelMode = options.agent !== void 0 || options.text !== void 0;
-  const rawMode = options.actor !== void 0 || options.payload !== void 0;
-  if (highLevelMode && rawMode) {
-    throw new InvalidArgumentError(
-      "Choose either high-level mode (--agent and --text) or raw mode (--actor and --payload), not both"
-    );
-  }
-  if (highLevelMode) {
-    const agent = trimString2(options.agent);
-    const text = trimString2(options.text);
-    if (!(agent && text)) {
-      throw new InvalidArgumentError(
-        "--agent and --text are required for high-level append mode"
-      );
+  if (action === "show") {
+    const fileConfig = await config.readConfig();
+    const apiKey = await config.readApiKey();
+    const fromEnv = trimString2(process.env.STARCITE_API_KEY);
+    let apiKeySource = "unset";
+    if (fromEnv) {
+      apiKeySource = "env";
+    } else if (apiKey) {
+      apiKeySource = "stored";
     }
-    return { kind: "high-level", agent, text };
-  }
-  if (rawMode) {
-    const actor = trimString2(options.actor);
-    const payload = trimString2(options.payload);
-    if (!(actor && payload)) {
-      throw new InvalidArgumentError(
-        "Raw append mode requires --actor and --payload, or use --agent and --text"
-      );
+    const output = {
+      endpoint: resolveConfiguredBaseUrl(fileConfig, globalOptions),
+      apiKey: apiKey ? "***" : null,
+      apiKeySource,
+      configDir: config.directory
+    };
+    if (globalOptions.json) {
+      runtime.writeJsonOutput(output, true);
+      return;
     }
-    return { kind: "raw", actor, payload };
+    runtime.logger.info(JSON.stringify(output, null, 2));
+    return;
   }
-  throw new InvalidArgumentError(
-    "append requires either high-level mode (--agent and --text) or raw mode (--actor and --payload)"
-  );
+  throw new CliUsageError("config requires `set` or `show`");
 }
-function toApiBaseUrlForContext(baseUrl) {
-  const parsed = new URL(baseUrl);
-  if (!(parsed.protocol === "http:" || parsed.protocol === "https:")) {
-    throw new InvalidArgumentError("base URL must use http:// or https://");
+
+// src/commands/create.ts
+var DEFAULT_CREATE_AGENT_ID2 = "starcite-cli";
+async function runCreateCommand(args, globalOptions, runtime) {
+  const parsed = parseArgs(
+    {
+      "--id": String,
+      "--title": String,
+      "--metadata": String
+    },
+    args
+  );
+  const metadata = parsed["--metadata"] ? parseJsonObject(parsed["--metadata"], "--metadata") : void 0;
+  const resolved = await runtime.resolveGlobalOptions(globalOptions);
+  const session = await resolved.client.session({
+    identity: resolved.client.agent({ id: DEFAULT_CREATE_AGENT_ID2 }),
+    id: parsed["--id"],
+    title: parsed["--title"],
+    metadata
+  });
+  if (resolved.json) {
+    runtime.writeJsonOutput(session.record ?? { id: session.id }, true);
+    return;
   }
-  const normalized = parsed.toString().replace(TRAILING_SLASHES_REGEX, "");
-  return normalized.endsWith("/v1") ? normalized : `${normalized}/v1`;
+  runtime.logger.info(session.id);
 }
-async function resolveSession(client, apiKey, sessionId) {
-  if (!apiKey) {
-    throw new InvalidArgumentError(
-      "append/tail require --token or a saved API key"
-    );
+
+// src/commands/sessions.ts
+async function runSessionsCommand(args, globalOptions, runtime) {
+  const parsed = parseArgs(
+    {
+      "--limit": String,
+      "--cursor": String,
+      "--metadata": String
+    },
+    args
+  );
+  if (`${parsed._[0] ?? ""}` !== "list") {
+    throw new CliUsageError("sessions requires `list`");
+  }
+  const cursor = trimString2(parsed["--cursor"]);
+  if (parsed["--cursor"] !== void 0 && !cursor) {
+    throw new CliUsageError("--cursor must be non-empty");
+  }
+  const resolved = await runtime.resolveGlobalOptions(globalOptions);
+  const page = await resolved.client.listSessions({
+    limit: parsed["--limit"] ? parsePositiveInteger(parsed["--limit"], "--limit") : void 0,
+    cursor,
+    metadata: parsed["--metadata"] ? parseSessionMetadataFilters(parsed["--metadata"]) : void 0
+  });
+  runtime.logger.error(
+    "Warning: `sessions list` is a bad call to use in production."
+  );
+  if (resolved.json) {
+    runtime.writeJsonOutput(page, true);
+    return;
   }
-  if (shouldAutoIssueSessionToken(apiKey)) {
-    return await client.session({
-      identity: resolveCreateIdentity(apiKey),
-      id: sessionId
-    });
+  if (page.sessions.length === 0) {
+    runtime.logger.info("No sessions found.");
+    return;
   }
-  const session = client.session({ token: apiKey });
-  if (session.id !== sessionId) {
-    throw new InvalidArgumentError(
-      `session token is bound to '${session.id}', expected '${sessionId}'`
+  runtime.logger.info("id	title	created_at");
+  for (const session of page.sessions) {
+    runtime.logger.info(
+      `${session.id}	${session.title ?? ""}	${session.created_at}`
     );
   }
-  return session;
-}
-function resolveCreateIdentity(apiKey, agentId = DEFAULT_CREATE_AGENT_ID) {
-  const tenantId = tokenTenantId(apiKey);
-  if (!tenantId) {
-    throw new InvalidArgumentError(
-      "session identity binding requires an API key with tenant_id claims"
-    );
+  if (page.next_cursor) {
+    runtime.logger.info(`next_cursor=${page.next_cursor}`);
   }
-  return new StarciteIdentity({
-    tenantId,
-    id: agentId,
-    type: "agent"
-  });
 }
-var StarciteCliApp = class {
-  createClient;
-  logger;
-  prompt;
-  runCommand;
-  constructor(deps = {}) {
-    this.createClient = deps.createClient ?? ((baseUrl, apiKey) => new Starcite({
-      baseUrl,
-      apiKey
-    }));
-    this.logger = deps.logger ?? defaultLogger;
-    this.prompt = deps.prompt ?? createDefaultPrompt();
-    this.runCommand = deps.runCommand ?? defaultCommandRunner;
-  }
-  buildProgram() {
-    const createClient = this.createClient;
-    const logger = this.logger;
-    const prompt = this.prompt;
-    const runCommand = this.runCommand;
-    const program = new Command();
-    program.name("starcite").description("Starcite CLI").showHelpAfterError().version(cliVersion, "-v, --version", "Print current CLI version").option("-u, --base-url <url>", "Starcite API base URL").option("-k, --token <token>", "Starcite API key").option(
-      "--config-dir <path>",
-      "Starcite CLI config directory (default: ~/.starcite)"
-    ).option("--json", "Output JSON");
-    program.command("version").description("Print current CLI version").action(() => {
-      logger.info(cliVersion);
-    });
-    program.command("config").description("Manage CLI configuration").addCommand(
-      new Command("set").description("Set a configuration value").argument("<key>", "endpoint | producer-id | api-key").argument("<value>", "value to store").action(async function(key, value) {
-        const { store } = await resolveGlobalOptions(this);
-        const parsedKey = parseConfigSetKey(key);
-        if (parsedKey === "endpoint") {
-          const endpoint = parseEndpoint(value, "endpoint");
-          await store.updateConfig({ baseUrl: endpoint });
-          logger.info(`Endpoint set to ${endpoint}`);
-          return;
-        }
-        if (parsedKey === "producer-id") {
-          const producerId = trimString2(value);
-          if (!producerId) {
-            throw new InvalidArgumentError("producer-id cannot be empty");
-          }
-          await store.updateConfig({ producerId });
-          logger.info(`Producer ID set to ${producerId}`);
-          return;
-        }
-        await store.saveApiKey(value);
-        await store.updateConfig({ apiKey: void 0 });
-        logger.info("API key saved.");
-      })
-    ).addCommand(
-      new Command("show").description("Show current configuration").action(async function() {
-        const { baseUrl, store } = await resolveGlobalOptions(this);
-        const config = await store.readConfig();
-        const apiKey = await store.readApiKey();
-        const fromEnv = trimString2(process.env.STARCITE_API_KEY);
-        let apiKeySource = "unset";
-        if (fromEnv) {
-          apiKeySource = "env";
-        } else if (apiKey) {
-          apiKeySource = "stored";
-        }
-        logger.info(
-          JSON.stringify(
-            {
-              endpoint: config.baseUrl ?? baseUrl,
-              producerId: config.producerId ?? null,
-              apiKey: apiKey ? "***" : null,
-              apiKeySource,
-              configDir: store.directory
-            },
-            null,
-            2
-          )
-        );
-      })
-    );
-    program.command("sessions").description("Manage sessions").addCommand(
-      new Command("list").description("List sessions").option(
-        "--limit <count>",
-        "Maximum sessions to return",
-        (value) => parsePositiveInteger(value, "--limit")
-      ).option("--cursor <cursor>", "Pagination cursor").option("--metadata <json>", "Metadata filter JSON object").action(async function(options) {
-        const resolved = await resolveGlobalOptions(this);
-        const { json } = resolved;
-        const client = resolved.apiKey ? createClient(resolved.baseUrl, resolved.apiKey) : createClient(resolved.baseUrl);
-        const metadata = options.metadata ? parseSessionMetadataFilters(options.metadata) : void 0;
-        const cursor = options.cursor?.trim();
-        if (options.cursor !== void 0 && !cursor) {
-          throw new InvalidArgumentError("--cursor must be non-empty");
-        }
-        const page = await client.listSessions({
-          limit: options.limit,
+
+// src/commands/tail.ts
+import {
+  SessionLogConflictError,
+  SessionLogGapError
+} from "@starcite/sdk";
+var DEFAULT_CREATE_AGENT_ID3 = "starcite-cli";
+async function runTailCommand(args, globalOptions, runtime) {
+  const parsed = parseArgs(
+    {
+      "--cursor": String,
+      "--agent": String,
+      "--limit": String,
+      "--no-follow": Boolean
+    },
+    args
+  );
+  const sessionId = `${parsed._[0] ?? ""}`;
+  if (!sessionId) {
+    throw new CliUsageError("tail requires <sessionId>");
+  }
+  const resolved = await runtime.resolveGlobalOptions(globalOptions);
+  const abortController = new AbortController();
+  const onSigint = () => {
+    abortController.abort();
+  };
+  const cursor = parsed["--cursor"] ? parseNonNegativeInteger(parsed["--cursor"], "--cursor") : 0;
+  const limit = parsed["--limit"] ? parseNonNegativeInteger(parsed["--limit"], "--limit") : void 0;
+  process.once("SIGINT", onSigint);
+  try {
+    let retriedAfterStoreReset = false;
+    while (true) {
+      const session = await resolved.client.session({
+        identity: resolved.client.agent({ id: DEFAULT_CREATE_AGENT_ID3 }),
+        id: sessionId
+      });
+      try {
+        await emitTailEvents({
+          session,
+          agent: parsed["--agent"],
           cursor,
-          metadata
+          follow: parsed["--no-follow"] !== true,
+          limit,
+          json: resolved.json,
+          runtime,
+          signal: abortController.signal
         });
-        if (json) {
-          logger.info(JSON.stringify(page, null, 2));
-          return;
-        }
-        if (page.sessions.length === 0) {
-          logger.info("No sessions found.");
-          return;
-        }
-        logger.info("id	title	created_at");
-        for (const session of page.sessions) {
-          logger.info(
-            `${session.id}	${session.title ?? ""}	${session.created_at}`
-          );
-        }
-        if (page.next_cursor) {
-          logger.info(`next_cursor=${page.next_cursor}`);
+        return;
+      } catch (error) {
+        const isStaleStoreConflict = error instanceof SessionLogConflictError || error instanceof SessionLogGapError;
+        if (!(isStaleStoreConflict && !retriedAfterStoreReset)) {
+          throw error;
         }
-      })
-    );
-    program.command("up").description("Start local Starcite services with Docker").option("-y, --yes", "Skip confirmation prompts and use defaults").option(
-      "--port <port>",
-      "Starcite API port",
-      (value) => parsePort2(value, "--port")
-    ).option(
-      "--db-port <port>",
-      "Postgres port",
-      (value) => parsePort2(value, "--db-port")
-    ).option("--image <image>", "Override Starcite image").action(async function(options) {
-      const { baseUrl, store } = await resolveGlobalOptions(this);
-      await runUpWizard({
-        baseUrl,
-        logger,
-        options,
-        prompt,
-        runCommand,
-        store
-      });
-    });
-    program.command("down").description("Stop and remove local Starcite services").option("-y, --yes", "Skip confirmation prompt").option("--no-volumes", "Keep Postgres volume data").action(async function(options) {
-      const { store } = await resolveGlobalOptions(this);
-      await runDownWizard({
-        logger,
-        options,
-        prompt,
-        runCommand,
-        store
-      });
-    });
-    program.command("create").description("Create a session").option("--id <id>", "Session ID").option("--title <title>", "Session title").option("--metadata <json>", "Session metadata JSON object").action(async function(options) {
-      const resolved = await resolveGlobalOptions(this);
-      const { json } = resolved;
-      const client = resolved.apiKey ? createClient(resolved.baseUrl, resolved.apiKey) : createClient(resolved.baseUrl);
-      const metadata = options.metadata ? parseJsonObject(options.metadata, "--metadata") : void 0;
-      const session = await client.session({
-        identity: resolveCreateIdentity(resolved.apiKey),
-        id: options.id,
-        title: options.title,
-        metadata
-      });
-      if (json) {
-        logger.info(
-          JSON.stringify(session.record ?? { id: session.id }, null, 2)
+        retriedAfterStoreReset = true;
+        resolved.store.clearSession(resolved.baseUrl, sessionId);
+        runtime.logger.error(
+          `Warning: cleared stale local session cache for '${sessionId}' and retried tail.`
         );
+      }
+    }
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+  }
+}
+async function emitTailEvents({
+  session,
+  agent,
+  cursor,
+  follow,
+  limit,
+  json,
+  runtime,
+  signal
+}) {
+  let emitted = 0;
+  for await (const { event } of session.tail({
+    cursor,
+    batchSize: DEFAULT_TAIL_BATCH_SIZE,
+    agent,
+    follow,
+    signal
+  })) {
+    if (limit !== void 0 && emitted >= limit) {
+      return;
+    }
+    if (json) {
+      runtime.writeJsonOutput(event);
+    } else {
+      runtime.logger.info(runtime.formatTailEvent(event));
+    }
+    emitted += 1;
+    if (limit !== void 0 && emitted >= limit) {
+      return;
+    }
+  }
+}
+
+// src/cli.ts
+var HELP_CODE = "commander.helpDisplayed";
+var HELP_TEXT = `Usage: starcite [options] <command>
+
+Commands:
+  config
+  create
+  append
+  tail
+  sessions
+
+Options:
+  -u, --base-url <url>   Starcite API base URL
+  -k, --token <token>    Starcite API key
+      --config-dir <path>
+      --json
+  -h, --help
+`;
+function normalizeArgv(argv, context) {
+  const args = context?.from === "user" ? [...argv] : argv.slice(2);
+  if (args[0] === "node" && typeof args[1] === "string" && args[1].includes("starcite")) {
+    return args.slice(2);
+  }
+  return args;
+}
+function parseGlobalArgs(args) {
+  const parsed = parseArgs(
+    {
+      "--base-url": String,
+      "-u": "--base-url",
+      "--token": String,
+      "-k": "--token",
+      "--config-dir": String,
+      "--json": Boolean,
+      "--help": Boolean,
+      "-h": "--help"
+    },
+    args,
+    true
+  );
+  return {
+    help: parsed["--help"] === true,
+    options: {
+      baseUrl: parsed["--base-url"],
+      configDir: parsed["--config-dir"],
+      token: parsed["--token"],
+      json: parsed["--json"] === true
+    },
+    rest: parsed._.map((value) => `${value}`)
+  };
+}
+function helpOutputText() {
+  return `${HELP_TEXT}
+`;
+}
+function buildProgram(deps = {}) {
+  const runtime = new CliRuntime(deps);
+  let shouldThrowOnHelp = false;
+  let output = {
+    writeOut(text) {
+      process.stdout.write(text);
+    },
+    writeErr(text) {
+      process.stderr.write(text);
+    }
+  };
+  return {
+    exitOverride() {
+      shouldThrowOnHelp = true;
+    },
+    configureOutput(next) {
+      output = {
+        writeOut: next.writeOut ?? output.writeOut,
+        writeErr: next.writeErr ?? output.writeErr
+      };
+    },
+    async parseAsync(argv, context) {
+      const parsed = parseGlobalArgs(normalizeArgv(argv, context));
+      const command = parsed.rest[0];
+      if (parsed.help || !command) {
+        output.writeOut(helpOutputText());
+        if (shouldThrowOnHelp) {
+          const error = new Error("Help displayed");
+          error.code = HELP_CODE;
+          throw error;
+        }
         return;
       }
-      logger.info(session.id);
-    });
-    program.command("append <sessionId>").description("Append an event").option("--agent <agent>", "Agent name (high-level mode)").option("--text <text>", "Text content (high-level mode)").option("--type <type>", "Event type", "content").option("--source <source>", "Event source").option(
-      "--producer-id <id>",
-      "Producer identity (auto-generated if omitted)"
-    ).option(
-      "--producer-seq <seq>",
-      "Producer sequence (defaults to persisted state, starting at 1)",
-      (value) => parsePositiveInteger(value, "--producer-seq")
-    ).option("--actor <actor>", "Raw actor field (raw mode)").option("--payload <json>", "Raw payload JSON object (raw mode)").option("--metadata <json>", "Event metadata JSON object").option("--refs <json>", "Event refs JSON object").option("--idempotency-key <key>", "Idempotency key").option(
-      "--expected-seq <seq>",
-      "Expected sequence",
-      (value) => parseNonNegativeInteger(value, "--expected-seq")
-    ).action(async function(sessionId, options) {
-      const { baseUrl, apiKey, json, store } = await resolveGlobalOptions(this);
-      const client = apiKey ? createClient(baseUrl, apiKey) : createClient(baseUrl);
-      const metadata = options.metadata ? parseJsonObject(options.metadata, "--metadata") : void 0;
-      const refs = options.refs ? parseJsonObject(options.refs, "--refs") : void 0;
-      const mode = resolveAppendMode(options);
-      const session = mode.kind === "high-level" && apiKey !== void 0 && shouldAutoIssueSessionToken(apiKey) ? await client.session({
-        identity: resolveCreateIdentity(apiKey, mode.agent),
-        id: sessionId
-      }) : await resolveSession(client, apiKey, sessionId);
-      const response = mode.kind === "high-level" ? await session.append({
-        type: options.type,
-        text: mode.text,
-        source: options.source,
-        metadata,
-        refs,
-        idempotencyKey: options.idempotencyKey,
-        expectedSeq: options.expectedSeq
-      }) : await store.withStateLock(async () => {
-        const producerId = await store.resolveProducerId(
-          options.producerId
-        );
-        const normalizedBaseUrl = toApiBaseUrlForContext(baseUrl);
-        const contextKey = buildSeqContextKey(
-          normalizedBaseUrl,
-          sessionId,
-          producerId
-        );
-        const producerSeq = options.producerSeq ?? await store.readNextSeq(contextKey);
-        const appendResponse = await session.appendRaw({
-          type: options.type,
-          payload: parseJsonObject(mode.payload, "--payload"),
-          actor: mode.actor,
-          producer_id: producerId,
-          producer_seq: producerSeq,
-          source: options.source,
-          metadata,
-          refs,
-          idempotency_key: options.idempotencyKey,
-          expected_seq: options.expectedSeq
-        });
-        await store.bumpNextSeq(contextKey, producerSeq);
-        return appendResponse;
-      });
-      if (json) {
-        logger.info(JSON.stringify(response, null, 2));
+      const commandArgs = parsed.rest.slice(1);
+      if (command === "config") {
+        await runConfigCommand(commandArgs, parsed.options, runtime);
         return;
       }
-      logger.info(`seq=${response.seq} deduped=${response.deduped}`);
-    });
-    program.command("tail <sessionId>").description("Tail events from a session").option(
-      "--cursor <cursor>",
-      "Replay cursor",
-      (value) => parseNonNegativeInteger(value, "--cursor")
-    ).option("--agent <agent>", "Filter by agent name").option(
-      "--limit <count>",
-      "Stop after N events",
-      (value) => parseNonNegativeInteger(value, "--limit")
-    ).option("--no-follow", "Exit after replaying stored events").action(async function(sessionId, options) {
-      const { baseUrl, apiKey, json } = await resolveGlobalOptions(this);
-      const client = apiKey ? createClient(baseUrl, apiKey) : createClient(baseUrl);
-      const session = await resolveSession(client, apiKey, sessionId);
-      const abortController = new AbortController();
-      const onSigint = () => {
-        abortController.abort();
-      };
-      process.once("SIGINT", onSigint);
-      try {
-        let emitted = 0;
-        await session.tail(
-          (event) => {
-            if (options.limit !== void 0 && emitted >= options.limit) {
-              abortController.abort();
-              return;
-            }
-            if (json) {
-              logger.info(JSON.stringify(event));
-            } else {
-              logger.info(formatTailEvent(event));
-            }
-            emitted += 1;
-            if (options.limit !== void 0 && emitted >= options.limit) {
-              abortController.abort();
-            }
-          },
-          {
-            cursor: options.cursor ?? 0,
-            batchSize: DEFAULT_TAIL_BATCH_SIZE,
-            agent: options.agent,
-            follow: options.follow,
-            signal: abortController.signal
-          }
-        );
-      } finally {
-        process.removeListener("SIGINT", onSigint);
+      if (command === "create") {
+        await runCreateCommand(commandArgs, parsed.options, runtime);
+        return;
       }
-    });
-    return program;
-  }
-  async run(argv = process.argv) {
-    const program = this.buildProgram();
-    try {
-      await program.parseAsync(argv);
-    } catch (error) {
-      if (error instanceof StarciteApiError) {
-        this.logger.error(`${error.code} (${error.status}): ${error.message}`);
-        process.exitCode = 1;
+      if (command === "append") {
+        await runAppendCommand(commandArgs, parsed.options, runtime);
         return;
       }
-      if (error instanceof Error) {
-        this.logger.error(error.message);
-        process.exitCode = 1;
+      if (command === "tail") {
+        await runTailCommand(commandArgs, parsed.options, runtime);
         return;
       }
-      this.logger.error("Unknown error");
+      if (command === "sessions") {
+        await runSessionsCommand(commandArgs, parsed.options, runtime);
+        return;
+      }
+      throw new CliUsageError(`Unknown command: ${command}`);
+    }
+  };
+}
+async function run(argv = process.argv, deps = {}) {
+  const runtime = new CliRuntime(deps);
+  const program = buildProgram(deps);
+  try {
+    await program.parseAsync(argv);
+  } catch (error) {
+    if (error instanceof StarciteApiError) {
+      runtime.logger.error(`${error.code} (${error.status}): ${error.message}`);
       process.exitCode = 1;
+      return;
     }
+    if (error instanceof Error) {
+      runtime.logger.error(error.message);
+      process.exitCode = 1;
+      return;
+    }
+    runtime.logger.error("Unknown error");
+    process.exitCode = 1;
   }
-};
-async function run(argv = process.argv, deps = {}) {
-  await new StarciteCliApp(deps).run(argv);
 }
 
 // src/index.ts