@vellumai/assistant 0.4.54 → 0.4.56

package/src/cli/commands/config.ts

@@ -1,4 +1,5 @@
 import type { Command } from "commander";
+import { z } from "zod";
 
 import {
   getNestedValue,
@@ -7,6 +8,8 @@ import {
   setNestedValue,
   syncConfigToLockfile,
 } from "../../config/loader.js";
+import { AssistantConfigSchema } from "../../config/schema.js";
+import { getSchemaAtPath } from "../../config/schema-utils.js";
 import { log } from "../logger.js";
 
 /**
@@ -48,8 +51,9 @@ and "assistant keys set <provider> <key>" to view and manage API keys.
 
 Examples:
   $ assistant config list
-  $ assistant config get provider
-  $ assistant config set provider anthropic
+  $ assistant config get services.inference.provider
+  $ assistant config schema services
+  $ assistant config set services.inference.provider anthropic
   $ assistant config set calls.enabled true`,
   );
 
@@ -62,8 +66,9 @@ Examples:
       "after",
       `
 Arguments:
-  key     Dotted path to the config key (e.g. provider, calls.enabled,
-          twilio.accountSid). Intermediate objects are created automatically.
+  key     Dotted path to the config key (e.g. services.inference.provider,
+          calls.enabled, twilio.accountSid). Intermediate objects are created
+          automatically.
   value   The value to store. Parsed as JSON first (so "true" becomes boolean
           true, "42" becomes number 42). Falls back to plain string if JSON
           parsing fails.
@@ -74,7 +79,7 @@ to reflect the updated configuration.
 To manage API keys, use "assistant keys set <provider> <key>" instead.
 
 Examples:
-  $ assistant config set provider anthropic
+  $ assistant config set services.inference.provider anthropic
   $ assistant config set calls.enabled true`,
     )
     .action((key: string, value: string) => {
@@ -99,7 +104,8 @@ Examples:
       "after",
       `
 Arguments:
-  key   Dotted path to the config key (e.g. provider, calls.enabled)
+  key   Dotted path to the config key (e.g. services.inference.provider,
+        calls.enabled)
 
 Prints the value at the given key path. If the key is not set, prints
 "(not set)". Object values are pretty-printed as indented JSON.
@@ -107,7 +113,7 @@ Prints the value at the given key path. If the key is not set, prints
 To view API keys, use "assistant keys list" instead.
 
 Examples:
-  $ assistant config get provider
+  $ assistant config get services.inference.provider
   $ assistant config get calls.enabled`,
     )
     .action((key: string) => {
@@ -124,6 +130,45 @@ Examples:
       }
     });
 
+  config
+    .command("schema [path]")
+    .description("Print the JSON Schema for the config (or a sub-path)")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  path   Optional dotted path to a config key (e.g. calls, memory.segmentation)
+
+Prints the JSON Schema for the entire config object, or the sub-schema at the
+given path. Useful for understanding available fields, their types, defaults,
+and constraints.
+
+Examples:
+  $ assistant config schema
+  $ assistant config schema calls
+  $ assistant config schema memory.segmentation`,
+    )
+    .action((path?: string) => {
+      if (!path) {
+        const jsonSchema = z.toJSONSchema(AssistantConfigSchema, {
+          unrepresentable: "any",
+        });
+        log.info(JSON.stringify(jsonSchema, null, 2));
+        return;
+      }
+
+      const subSchema = getSchemaAtPath(AssistantConfigSchema, path);
+      if (!subSchema) {
+        log.error(`No schema found at path: ${path}`);
+        process.exit(1);
+      }
+
+      const jsonSchema = z.toJSONSchema(subSchema, {
+        unrepresentable: "any",
+      });
+      log.info(JSON.stringify(jsonSchema, null, 2));
+    });
+
   config
     .command("list")
     .description("List all config values")

package/src/cli/commands/{sessions.ts → conversations.ts}

@@ -21,43 +21,45 @@ import { timeAgo } from "../../util/time.js";
 import { initializeDb } from "../db.js";
 import { log } from "../logger.js";
 
-export function registerSessionsCommand(program: Command): void {
-  const sessions = program.command("sessions").description("Manage sessions");
+export function registerConversationsCommand(program: Command): void {
+  const conversations = program
+    .command("conversations")
+    .description("Manage conversations");
 
-  sessions.addHelpText(
+  conversations.addHelpText(
     "after",
     `
-Sessions represent conversation threads with the assistant. Each session has a
-unique ID and a title. The assistant must be running for "new" (it communicates
-via the HTTP API), while "list", "export", and "clear" operate on the local
-SQLite database directly.
+Conversations with the assistant. Each conversation has a unique ID and a
+title. The assistant must be running for "new" (it communicates via the HTTP
+API), while "list", "export", and "clear" operate on the local SQLite database
+directly.
 
 Examples:
-  $ assistant sessions list
-  $ assistant sessions new "Project planning"
-  $ assistant sessions export
-  $ assistant sessions clear`,
+  $ assistant conversations list
+  $ assistant conversations new "Project planning"
+  $ assistant conversations export
+  $ assistant conversations clear`,
   );
 
-  sessions
+  conversations
     .command("list")
-    .description("List all sessions")
+    .description("List all conversations")
     .addHelpText(
       "after",
       `
-Shows all sessions with their ID, title, and a relative timestamp (e.g.
-"3 hours ago"). Sessions are listed in order of most recently updated.
+Shows all conversations with their ID, title, and a relative timestamp (e.g.
+"3 hours ago"). Conversations are listed in order of most recently updated.
 
 Operates on the local SQLite database directly — does not require the assistant.
 
 Examples:
-  $ assistant sessions list`,
+  $ assistant conversations list`,
     )
     .action(async () => {
       initializeDb();
       const all = listConversations(Number.MAX_SAFE_INTEGER);
       if (all.length === 0) {
-        log.info("No sessions");
+        log.info("No conversations");
       } else {
         for (const s of all) {
           log.info(
@@ -67,34 +69,34 @@ Examples:
       }
     });
 
-  sessions
+  conversations
     .command("new [title]")
-    .description("Create a new session")
+    .description("Create a new conversation")
     .addHelpText(
       "after",
       `
 Arguments:
-  title   Optional session title (string). If omitted, a default title is
+  title   Optional conversation title (string). If omitted, a default title is
           assigned by the assistant.
 
-Creates a new conversation session and prints its title and ID.
+Creates a new conversation and prints its title and ID.
 
 Examples:
-  $ assistant sessions new
-  $ assistant sessions new "Project planning"
-  $ assistant sessions new "Bug triage 2026-03-05"`,
+  $ assistant conversations new
+  $ assistant conversations new "Project planning"
+  $ assistant conversations new "Bug triage 2026-03-05"`,
     )
     .action(async (title?: string) => {
       if (shouldAutoStartDaemon()) await ensureDaemonRunning();
       initializeDb();
       const conversation = createConversation(title);
       log.info(
-        `Created session: ${conversation.title ?? "New Conversation"} (${conversation.id})`,
+        `Created conversation: ${conversation.title ?? "New Conversation"} (${conversation.id})`,
       );
     });
 
-  sessions
-    .command("export [sessionId]")
+  conversations
+    .command("export [conversationId]")
     .description("Export a conversation as markdown or JSON")
     .option("-f, --format <format>", "Output format: md or json", "md")
     .option("-o, --output <file>", "Write to file instead of stdout")
@@ -102,9 +104,10 @@ Examples:
       "after",
       `
 Arguments:
-  sessionId   Optional session ID (or unique prefix). Defaults to the most
-              recent session. Supports prefix matching — e.g. "abc123" matches
-              the first session whose ID starts with "abc123".
+  conversationId   Optional conversation ID (or unique prefix). Defaults to the
+                   most recent conversation. Supports prefix matching — e.g.
+                   "abc123" matches the first conversation whose ID starts with
+                   "abc123".
 
 Two output formats are available:
   md    Markdown conversation transcript (default). Human-readable rendering
@@ -115,13 +118,13 @@ Two output formats are available:
 Operates on the local SQLite database directly — does not require the assistant.
 
 Examples:
-  $ assistant sessions export
-  $ assistant sessions export --format json -o conversation.json
-  $ assistant sessions export abc123 --format md`,
+  $ assistant conversations export
+  $ assistant conversations export --format json -o conversation.json
+  $ assistant conversations export abc123 --format md`,
     )
     .action(
       async (
-        sessionId?: string,
+        conversationId?: string,
         opts?: { format: string; output?: string },
       ) => {
         initializeDb();
@@ -131,17 +134,17 @@ Examples:
           process.exit(1);
         }
 
-        let id = sessionId;
+        let id = conversationId;
         if (!id) {
           const all = listConversations(1);
           if (all.length === 0) {
-            log.error("No sessions found");
+            log.error("No conversations found");
             process.exit(1);
           }
           id = all[0].id;
         }
 
-        // Support prefix matching for session IDs
+        // Support prefix matching for conversation IDs
         let conversation = getConversation(id);
         if (!conversation) {
           const all = listConversations(Number.MAX_SAFE_INTEGER);
@@ -149,7 +152,7 @@ Examples:
           if (match) {
             conversation = match;
           } else {
-            log.error(`Session not found: ${id}`);
+            log.error(`Conversation not found: ${id}`);
             process.exit(1);
           }
         }
@@ -179,7 +182,7 @@ Examples:
       },
     );
 
-  sessions
+  conversations
     .command("clear")
     .description(
       "Clear all conversations, messages, and vector data (dev only)",
@@ -198,7 +201,7 @@ the assistant.
 Intended for development use. This action cannot be undone.
 
 Examples:
-  $ assistant sessions clear`,
+  $ assistant conversations clear`,
     )
     .action(async () => {
       log.info(

package/src/cli/commands/credential-execution.ts

@@ -0,0 +1,345 @@
+/**
+ * CLI surfaces for CES grant listing, grant revocation, and audit inspection.
+ *
+ * These commands communicate with the Credential Execution Service via
+ * the CES RPC client to inspect and manage CES-owned state. They never
+ * expose raw secrets, raw tokens, or raw headers/bodies — only sanitized
+ * metadata and audit summaries.
+ *
+ * Commands:
+ * - `credential-execution grants list` — List current CES grants.
+ * - `credential-execution grants revoke <id>` — Revoke a grant by stable ID.
+ * - `credential-execution audit list` — List recent audit records.
+ */
+
+import {
+  type AuditRecordSummary,
+  CesRpcMethod,
+  type ListAuditRecordsResponse,
+  type ListGrantsResponse,
+  type PersistentGrantRecord,
+  type RevokeGrantResponse,
+} from "@vellumai/ces-contracts";
+import type { Command } from "commander";
+
+import { getConfig } from "../../config/loader.js";
+import {
+  type CesClient,
+  createCesClient,
+} from "../../credential-execution/client.js";
+import { isCesGrantAuditEnabled } from "../../credential-execution/feature-gates.js";
+import { createCesProcessManager } from "../../credential-execution/process-manager.js";
+import { log } from "../logger.js";
+import { shouldOutputJson, writeOutput } from "../output.js";
+
+// ---------------------------------------------------------------------------
+// Runtime feature gate
+// ---------------------------------------------------------------------------
+
+/**
+ * Check the ces-grant-audit feature flag and bail with a clear message if
+ * disabled. Returns `true` when the gate is open, `false` (with output
+ * written) when the feature is off.
+ */
+function ensureGrantAuditEnabled(cmd: Command): boolean {
+  if (isCesGrantAuditEnabled(getConfig())) return true;
+
+  writeOutput(cmd, {
+    ok: false,
+    error:
+      "CES grant/audit inspection is disabled (feature_flags.ces-grant-audit.enabled is off)",
+  });
+  process.exitCode = 1;
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// CES client lifecycle helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Spin up a CES process (or connect to the sidecar), perform the handshake,
+ * and return a ready client. The caller must call `cleanup()` when done.
+ */
+async function acquireCesClient(): Promise<{
+  client: CesClient;
+  cleanup: () => Promise<void>;
+}> {
+  const pm = createCesProcessManager({ assistantConfig: getConfig() });
+  const transport = await pm.start();
+  const client = createCesClient(transport);
+
+  try {
+    const hs = await client.handshake();
+
+    if (!hs.accepted) {
+      throw new Error(`CES handshake rejected: ${hs.reason ?? "unknown"}`);
+    }
+  } catch (err) {
+    client.close();
+    await pm.stop();
+    throw err;
+  }
+
+  return {
+    client,
+    cleanup: async () => {
+      client.close();
+      await pm.stop();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Human-readable formatters
+// ---------------------------------------------------------------------------
+
+function printGrantHuman(grant: PersistentGrantRecord): void {
+  log.info(`  Grant ${grant.grantId}`);
+  log.info(`    Handle:       ${grant.credentialHandle}`);
+  log.info(`    Type:         ${grant.proposalType}`);
+  log.info(`    Status:       ${grant.status}`);
+  log.info(`    Granted by:   ${grant.grantedBy}`);
+  log.info(`    Created:      ${grant.createdAt}`);
+  if (grant.expiresAt) log.info(`    Expires:      ${grant.expiresAt}`);
+  if (grant.allowedPurposes.length > 0) {
+    log.info(`    Purposes:     ${grant.allowedPurposes.join(", ")}`);
+  }
+}
+
+function printAuditRecordHuman(record: AuditRecordSummary): void {
+  log.info(`  ${record.timestamp}  ${record.toolName}  ${record.target}`);
+  log.info(`    Audit ID:     ${record.auditId}`);
+  log.info(`    Grant:        ${record.grantId}`);
+  log.info(`    Handle:       ${record.credentialHandle}`);
+  log.info(`    Success:      ${record.success}`);
+  if (record.errorMessage) {
+    log.info(`    Error:        ${record.errorMessage}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
+export function registerCredentialExecutionCommand(program: Command): void {
+  const ce = program
+    .command("credential-execution")
+    .description(
+      "Inspect and manage Credential Execution Service (CES) grants and audit records",
+    )
+    .option("--json", "Machine-readable compact JSON output");
+
+  // -------------------------------------------------------------------------
+  // grants
+  // -------------------------------------------------------------------------
+
+  const grants = ce.command("grants").description("Manage CES grants");
+
+  // grants list
+  grants
+    .command("list")
+    .description("List current CES grants")
+    .option("--handle <handle>", "Filter by credential handle")
+    .option(
+      "--status <status>",
+      "Filter by grant status (active, expired, revoked, consumed)",
+    )
+    .addHelpText(
+      "after",
+      `
+Lists all persistent grants tracked by the Credential Execution Service.
+Each grant authorizes a specific credential handle for a constrained purpose.
+
+Grant records never include raw secret values — only metadata (handle,
+proposal type, status, timestamps, allowed purposes).
+
+Examples:
+  $ assistant credential-execution grants list
+  $ assistant credential-execution grants list --handle local_static:github/token
+  $ assistant credential-execution grants list --status active --json`,
+    )
+    .action(
+      async (opts: { handle?: string; status?: string }, cmd: Command) => {
+        let cleanup: (() => Promise<void>) | undefined;
+        try {
+          if (!ensureGrantAuditEnabled(cmd)) return;
+          const ces = await acquireCesClient();
+          cleanup = ces.cleanup;
+
+          const response: ListGrantsResponse = await ces.client.call(
+            CesRpcMethod.ListGrants as typeof CesRpcMethod.ListGrants,
+            {
+              credentialHandle: opts.handle,
+              status: opts.status as
+                | "active"
+                | "expired"
+                | "revoked"
+                | "consumed"
+                | undefined,
+            },
+          );
+
+          writeOutput(cmd, { ok: true, grants: response.grants });
+
+          if (!shouldOutputJson(cmd)) {
+            if (response.grants.length === 0) {
+              log.info("No CES grants found");
+            } else {
+              log.info(`${response.grants.length} CES grant(s):\n`);
+              for (const grant of response.grants) {
+                printGrantHuman(grant);
+                log.info("");
+              }
+            }
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        } finally {
+          if (cleanup) await cleanup();
+        }
+      },
+    );
+
+  // grants revoke
+  grants
+    .command("revoke <grantId>")
+    .description("Revoke a CES grant by its stable ID")
+    .option("--reason <reason>", "Human-readable reason for revocation")
+    .addHelpText(
+      "after",
+      `
+Revokes a specific CES grant, immediately preventing any further use of
+that grant for credentialed operations. The grant is permanently removed
+from CES state.
+
+Arguments:
+  grantId   The stable grant identifier (UUID)
+
+Examples:
+  $ assistant credential-execution grants revoke 7a3b1c2d-4e5f-6789-abcd-ef0123456789
+  $ assistant credential-execution grants revoke abc123 --reason "credential rotated"`,
+    )
+    .action(
+      async (grantId: string, opts: { reason?: string }, cmd: Command) => {
+        let cleanup: (() => Promise<void>) | undefined;
+        try {
+          if (!ensureGrantAuditEnabled(cmd)) return;
+          const ces = await acquireCesClient();
+          cleanup = ces.cleanup;
+
+          const response: RevokeGrantResponse = await ces.client.call(
+            CesRpcMethod.RevokeGrant as typeof CesRpcMethod.RevokeGrant,
+            {
+              grantId,
+              reason: opts.reason,
+            },
+          );
+
+          if (response.success) {
+            writeOutput(cmd, { ok: true, grantId });
+
+            if (!shouldOutputJson(cmd)) {
+              log.info(`Revoked grant ${grantId}`);
+            }
+          } else {
+            writeOutput(cmd, {
+              ok: false,
+              error: response.error?.message ?? "Failed to revoke grant",
+            });
+            process.exitCode = 1;
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        } finally {
+          if (cleanup) await cleanup();
+        }
+      },
+    );
+
+  // -------------------------------------------------------------------------
+  // audit
+  // -------------------------------------------------------------------------
+
+  const audit = ce.command("audit").description("Inspect CES audit records");
+
+  // audit list
+  audit
+    .command("list")
+    .description("List recent CES audit records")
+    .option("--handle <handle>", "Filter by credential handle")
+    .option("--grant <grantId>", "Filter by grant ID")
+    .option("-l, --limit <n>", "Maximum number of records to return", "20")
+    .addHelpText(
+      "after",
+      `
+Lists recent audit records from the Credential Execution Service. Each
+record is a token-free summary of a credentialed operation (HTTP request
+or secure command execution).
+
+Audit records never include raw secrets, raw tokens, raw headers, or raw
+response bodies — only sanitized metadata (method, URL template, status
+code, credential handle, grant ID, success/failure).
+
+Examples:
+  $ assistant credential-execution audit list
+  $ assistant credential-execution audit list --limit 50
+  $ assistant credential-execution audit list --handle local_static:github/token
+  $ assistant credential-execution audit list --grant abc123 --json`,
+    )
+    .action(
+      async (
+        opts: { handle?: string; grant?: string; limit: string },
+        cmd: Command,
+      ) => {
+        let cleanup: (() => Promise<void>) | undefined;
+        try {
+          if (!ensureGrantAuditEnabled(cmd)) return;
+          const ces = await acquireCesClient();
+          cleanup = ces.cleanup;
+
+          const limit = parseInt(opts.limit, 10) || 20;
+
+          const response: ListAuditRecordsResponse = await ces.client.call(
+            CesRpcMethod.ListAuditRecords as typeof CesRpcMethod.ListAuditRecords,
+            {
+              credentialHandle: opts.handle,
+              grantId: opts.grant,
+              limit,
+            },
+          );
+
+          writeOutput(cmd, {
+            ok: true,
+            records: response.records,
+            nextCursor: response.nextCursor,
+          });
+
+          if (!shouldOutputJson(cmd)) {
+            if (response.records.length === 0) {
+              log.info("No CES audit records found");
+            } else {
+              log.info(`${response.records.length} CES audit record(s):\n`);
+              for (const record of response.records) {
+                printAuditRecordHuman(record);
+                log.info("");
+              }
+              if (response.nextCursor) {
+                log.info("(more records available — use --limit to increase)");
+              }
+            }
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        } finally {
+          if (cleanup) await cleanup();
+        }
+      },
+    );
+}