starcite 0.0.3 → 0.0.5

package/dist/index.js

@@ -2,9 +2,9 @@
 
 // src/cli.ts
 import {
-  createStarciteClient,
-  normalizeBaseUrl,
-  StarciteApiError
+  Starcite,
+  StarciteApiError,
+  StarciteIdentity
 } from "@starcite/sdk";
 import { Command, InvalidArgumentError } from "commander";
 import { createConsola } from "consola";
@@ -13,7 +13,7 @@ import { z as z2 } from "zod";
 // package.json
 var package_default = {
   name: "starcite",
-  version: "0.0.3",
+  version: "0.0.5",
   description: "CLI for Starcite",
   license: "Apache-2.0",
   homepage: "https://starcite.ai",
@@ -45,6 +45,7 @@ var package_default = {
     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",
@@ -55,7 +56,7 @@ var package_default = {
   },
   dependencies: {
     "@clack/prompts": "^1.0.1",
-    "@starcite/sdk": "^0.0.2",
+    "@starcite/sdk": "^0.0.5",
     commander: "^13.1.0",
     conf: "^15.1.0",
     consola: "^3.4.2",
@@ -630,7 +631,15 @@ 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) {
@@ -683,27 +692,19 @@ function parseConfigSetKey(value) {
     "config key must be one of: endpoint, producer-id, api-key"
   );
 }
-function parseJsonOption(value, schema, optionName, invalidShapeMessage) {
+function parseJsonObject(value, optionName) {
   let parsed;
   try {
     parsed = JSON.parse(value);
   } catch {
     throw new InvalidArgumentError(`${optionName} must be valid JSON`);
   }
-  const result = schema.safeParse(parsed);
+  const result = jsonObjectSchema.safeParse(parsed);
   if (!result.success) {
-    throw new InvalidArgumentError(
-      `${optionName} must be ${invalidShapeMessage}`
-    );
+    throw new InvalidArgumentError(`${optionName} must be a JSON object`);
   }
   return result.data;
 }
-function parseJsonObject(value, optionName) {
-  return parseJsonOption(value, jsonObjectSchema, optionName, "a JSON object");
-}
-function parseEventRefs(value) {
-  return parseJsonObject(value, "--refs");
-}
 function parseSessionMetadataFilters(value) {
   const parsed = parseJsonObject(value, "--metadata");
   const filters = {};
@@ -719,7 +720,12 @@ function parseSessionMetadataFilters(value) {
   return filters;
 }
 function getGlobalOptions(command) {
-  return command.optsWithGlobals();
+  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();
@@ -742,403 +748,439 @@ async function resolveGlobalOptions(command) {
     store
   };
 }
-async function promptForEndpoint(prompt, defaultEndpoint) {
-  while (true) {
-    const answer = await prompt.input("Starcite endpoint URL", defaultEndpoint);
-    try {
-      return parseEndpoint(answer, "endpoint");
-    } catch {
-    }
+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)}`;
 }
-async function promptForApiKey(prompt) {
-  const message = "Paste your Starcite API key";
-  const answer = prompt.password ? await prompt.password(message) : await prompt.input(message, "");
-  return trimString2(answer) ?? "";
+function parseJwtClaims(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) {
+    return void 0;
+  }
+  const payload = parts[1];
+  if (!payload) {
+    return void 0;
+  }
+  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;
+  }
 }
-function formatTailEvent(event) {
-  const actorLabel = event.agent ?? event.actor;
-  if (event.text) {
-    return `[${actorLabel}] ${event.text}`;
+function tokenTenantId(token) {
+  if (!token) {
+    return void 0;
   }
-  return `[${actorLabel}] ${JSON.stringify(event.payload)}`;
+  const claims = parseJwtClaims(token);
+  const tenantId = claims?.tenant_id;
+  if (typeof tenantId !== "string") {
+    return void 0;
+  }
+  const trimmed = tenantId.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
 }
-function buildProgram(deps = {}) {
-  const createClient = deps.createClient ?? ((baseUrl, apiKey) => createStarciteClient({
-    baseUrl,
-    apiKey
-  }));
-  const logger = deps.logger ?? defaultLogger;
-  const prompt = deps.prompt ?? createDefaultPrompt();
-  const runCommand = deps.runCommand ?? defaultCommandRunner;
-  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 / service JWT").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("init").description("Initialize Starcite CLI config for a remote instance").option("--endpoint <url>", "Starcite endpoint URL").option("--api-key <key>", "API key to store").option("-y, --yes", "Skip prompts and only use provided options").action(async function initAction(options) {
-    const { baseUrl, json, store } = await resolveGlobalOptions(this);
-    const defaultEndpoint = parseEndpoint(baseUrl, "endpoint");
-    let endpoint = defaultEndpoint;
-    if (options.endpoint) {
-      endpoint = parseEndpoint(options.endpoint, "--endpoint");
-    } else if (!options.yes) {
-      endpoint = await promptForEndpoint(prompt, defaultEndpoint);
-    }
-    await store.updateConfig({ baseUrl: endpoint });
-    let apiKey = trimString2(options.apiKey);
-    if (!(apiKey || options.yes)) {
-      apiKey = await promptForApiKey(prompt);
+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);
+      }
     }
-    if (apiKey) {
-      await store.saveApiKey(apiKey);
-      await store.updateConfig({ apiKey: void 0 });
+  }
+  const scopesClaim = claims.scopes;
+  if (Array.isArray(scopesClaim)) {
+    for (const scope of scopesClaim) {
+      if (typeof scope === "string" && scope.length > 0) {
+        scopes.add(scope);
+      }
     }
-    if (json) {
-      logger.info(
-        JSON.stringify(
-          {
-            configDir: store.directory,
-            endpoint,
-            apiKeySaved: Boolean(apiKey)
-          },
-          null,
-          2
-        )
+  }
+  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"
       );
-      return;
     }
-    logger.info(`Initialized Starcite CLI in ${store.directory}`);
-    logger.info(`Endpoint set to ${endpoint}`);
-    if (apiKey) {
-      logger.info("API key saved. You can now run create/append/tail.");
-    } else {
-      logger.info("API key not set. Run `starcite auth login` when ready.");
+    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"
+      );
     }
+    return { kind: "raw", actor, payload };
+  }
+  throw new InvalidArgumentError(
+    "append requires either high-level mode (--agent and --text) or raw mode (--actor and --payload)"
+  );
+}
+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://");
+  }
+  const normalized = parsed.toString().replace(TRAILING_SLASHES_REGEX, "");
+  return normalized.endsWith("/v1") ? normalized : `${normalized}/v1`;
+}
+async function resolveSession(client, apiKey, sessionId) {
+  if (!apiKey) {
+    throw new InvalidArgumentError(
+      "append/tail require --token or a saved API key"
+    );
+  }
+  if (shouldAutoIssueSessionToken(apiKey)) {
+    return await client.session({
+      identity: resolveCreateIdentity(apiKey),
+      id: sessionId
+    });
+  }
+  const session = client.session({ token: apiKey });
+  if (session.id !== sessionId) {
+    throw new InvalidArgumentError(
+      `session token is bound to '${session.id}', expected '${sessionId}'`
+    );
+  }
+  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"
+    );
+  }
+  return new StarciteIdentity({
+    tenantId,
+    id: agentId,
+    type: "agent"
   });
-  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 configSetAction(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");
+}
+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;
         }
-        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 configShowAction() {
+        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,
+          cursor,
+          metadata
+        });
+        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}`);
+        }
+      })
+    );
+    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);
-      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("auth").description("Manage API key authentication").addCommand(
-    new Command("login").description("Save an API key for authenticated requests").option("--api-key <key>", "API key to store").action(async function authLoginAction(options) {
-      const { store } = await resolveGlobalOptions(this);
-      let apiKey = trimString2(options.apiKey);
-      if (!apiKey) {
-        apiKey = await promptForApiKey(prompt);
-      }
-      if (!apiKey) {
-        throw new Error("API key cannot be empty");
-      }
-      await store.saveApiKey(apiKey);
-      await store.updateConfig({ apiKey: void 0 });
-      logger.info("API key saved.");
-    })
-  ).addCommand(
-    new Command("logout").description("Remove the saved API key").action(async function authLogoutAction() {
-      const { store } = await resolveGlobalOptions(this);
-      await store.clearApiKey();
-      logger.info("Saved API key removed.");
-    })
-  ).addCommand(
-    new Command("status").description("Show authentication status").action(async function authStatusAction() {
+      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);
-      const apiKey = await store.readApiKey();
-      const fromEnv = trimString2(process.env.STARCITE_API_KEY);
-      if (fromEnv) {
-        logger.info("Authenticated via STARCITE_API_KEY.");
-        return;
-      }
-      if (apiKey) {
-        logger.info("Authenticated via saved API key.");
-        return;
-      }
-      logger.info("No API key configured. Run `starcite auth login`.");
-    })
-  );
-  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 sessionsListAction(options) {
-      const { baseUrl, apiKey, json } = await resolveGlobalOptions(this);
-      const client = apiKey ? createClient(baseUrl, apiKey) : createClient(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,
-        cursor,
+      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(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}`
+          JSON.stringify(session.record ?? { id: session.id }, null, 2)
         );
+        return;
       }
-      if (page.next_cursor) {
-        logger.info(`next_cursor=${page.next_cursor}`);
-      }
-    })
-  );
-  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 upAction(options) {
-    const { baseUrl, store } = await resolveGlobalOptions(this);
-    await runUpWizard({
-      baseUrl,
-      logger,
-      options,
-      prompt,
-      runCommand,
-      store
+      logger.info(session.id);
     });
-  });
-  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 downAction(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 createAction(options) {
-    const { baseUrl, apiKey, json } = await resolveGlobalOptions(this);
-    const client = apiKey ? createClient(baseUrl, apiKey) : createClient(baseUrl);
-    const metadata = options.metadata ? parseJsonObject(options.metadata, "--metadata") : void 0;
-    const session = await client.create({
-      id: options.id,
-      title: options.title,
-      metadata
+    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));
+        return;
+      }
+      logger.info(`seq=${response.seq} deduped=${response.deduped}`);
     });
-    if (json) {
-      logger.info(
-        JSON.stringify(session.record ?? { id: session.id }, null, 2)
-      );
-      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 appendAction(sessionId, options) {
-    const { baseUrl, apiKey, json, store } = await resolveGlobalOptions(this);
-    const client = apiKey ? createClient(baseUrl, apiKey) : createClient(baseUrl);
-    const session = client.session(sessionId);
-    const metadata = options.metadata ? parseJsonObject(options.metadata, "--metadata") : void 0;
-    const refs = options.refs ? parseEventRefs(options.refs) : void 0;
-    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 Error(
-        "Choose either high-level mode (--agent and --text) or raw mode (--actor and --payload), not both"
-      );
-    }
-    const producerId = await store.resolveProducerId(options.producerId);
-    const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
-    const contextKey = buildSeqContextKey(
-      normalizedBaseUrl,
-      sessionId,
-      producerId
-    );
-    const response = await store.withStateLock(async () => {
-      const producerSeq = options.producerSeq ?? await store.readNextSeq(contextKey);
-      const appendOptions = {
-        ...options,
-        producerId,
-        producerSeq
+    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();
       };
-      const appendResponse = highLevelMode ? await appendHighLevel(session, appendOptions, metadata, refs) : await appendRaw(session, appendOptions, metadata, refs);
-      await store.bumpNextSeq(contextKey, producerSeq);
-      return appendResponse;
+      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 (json) {
-      logger.info(JSON.stringify(response, null, 2));
-      return;
-    }
-    logger.info(
-      `seq=${response.seq} last_seq=${response.last_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 tailAction(sessionId, options) {
-    const { baseUrl, apiKey, json } = await resolveGlobalOptions(this);
-    const client = apiKey ? createClient(baseUrl, apiKey) : createClient(baseUrl);
-    const session = client.session(sessionId);
-    const abortController = new AbortController();
-    const onSigint = () => {
-      abortController.abort();
-    };
-    process.once("SIGINT", onSigint);
+    return program;
+  }
+  async run(argv = process.argv) {
+    const program = this.buildProgram();
     try {
-      let emitted = 0;
-      for await (const event of session.tail({
-        cursor: options.cursor ?? 0,
-        agent: options.agent,
-        follow: options.follow,
-        signal: abortController.signal
-      })) {
-        if (json) {
-          logger.info(JSON.stringify(event));
-        } else {
-          logger.info(formatTailEvent(event));
-        }
-        emitted += 1;
-        if (options.limit !== void 0 && emitted >= options.limit) {
-          abortController.abort();
-          break;
-        }
+      await program.parseAsync(argv);
+    } catch (error) {
+      if (error instanceof StarciteApiError) {
+        this.logger.error(`${error.code} (${error.status}): ${error.message}`);
+        process.exitCode = 1;
+        return;
       }
-    } finally {
-      process.removeListener("SIGINT", onSigint);
-    }
-  });
-  return program;
-}
-function appendHighLevel(session, options, metadata, refs) {
-  if (!(options.agent && options.text)) {
-    throw new Error(
-      "--agent and --text are required for high-level append mode"
-    );
-  }
-  return session.append({
-    agent: options.agent,
-    producerId: options.producerId,
-    producerSeq: options.producerSeq,
-    text: options.text,
-    type: options.type,
-    source: options.source,
-    metadata,
-    refs,
-    idempotencyKey: options.idempotencyKey,
-    expectedSeq: options.expectedSeq
-  });
-}
-function appendRaw(session, options, metadata, refs) {
-  if (!(options.actor && options.payload)) {
-    throw new Error(
-      "Raw append mode requires --actor and --payload, or use --agent and --text"
-    );
-  }
-  return session.appendRaw({
-    type: options.type,
-    payload: parseJsonObject(options.payload, "--payload"),
-    actor: options.actor,
-    producer_id: options.producerId,
-    producer_seq: options.producerSeq,
-    source: options.source,
-    metadata,
-    refs,
-    idempotency_key: options.idempotencyKey,
-    expected_seq: options.expectedSeq
-  });
-}
-async function run(argv = process.argv, deps = {}) {
-  const program = buildProgram(deps);
-  try {
-    await program.parseAsync(argv);
-  } catch (error) {
-    if (error instanceof StarciteApiError) {
-      const logger2 = deps.logger ?? defaultLogger;
-      logger2.error(`${error.code} (${error.status}): ${error.message}`);
-      process.exitCode = 1;
-      return;
-    }
-    if (error instanceof Error) {
-      const logger2 = deps.logger ?? defaultLogger;
-      logger2.error(error.message);
+      if (error instanceof Error) {
+        this.logger.error(error.message);
+        process.exitCode = 1;
+        return;
+      }
+      this.logger.error("Unknown error");
       process.exitCode = 1;
-      return;
     }
-    const logger = deps.logger ?? defaultLogger;
-    logger.error("Unknown error");
-    process.exitCode = 1;
   }
+};
+async function run(argv = process.argv, deps = {}) {
+  await new StarciteCliApp(deps).run(argv);
 }
 
 // src/index.ts