@secondcontext/btx-cli 0.0.3 → 0.0.6

package/README.md

@@ -36,7 +36,7 @@ Install the tarball into a clean repo or temp directory:
 
 ```bash
 npm init -y
-npm install /absolute/path/to/code/packages/btx-cli/secondcontext-btx-cli-0.0.3.tgz
+npm install /absolute/path/to/code/packages/btx-cli/secondcontext-btx-cli-0.0.5.tgz
 ./node_modules/.bin/btx --help
 ./node_modules/.bin/btx repo status --json
 ```
@@ -50,6 +50,11 @@ btx logout
 btx setup
 btx setup codex
 btx projects
+btx messages list
+btx messages send "Shipped the fix"
+btx messages send "Can you review this?" --peer faruk@secondcontext.com
+btx messages conversations
+btx messages members
 btx repo link <project-id>
 btx bootstrap all
 btx context get --json
@@ -61,9 +66,11 @@ btx session finish --summary "Recorded outcome and next steps"
 
 ## Auth and repo state
 
-- `btx login` imports an existing desktop auth session when available, or opens a browser flow that writes `~/.btx/auth-session.json`
+- `btx login` reuses an existing desktop or standalone auth session when it is still valid, or opens a browser flow that writes `~/.btx/auth-session.json`
 - `btx login status` shows whether the CLI is authenticated and whether desktop fallback is enabled
 - `btx logout` clears the standalone CLI session and disables desktop fallback so the CLI stays logged out. Use `btx logout --all` to also clear the desktop session file
+- `btx messages list` reads BTX project chat, with `--peer` for direct messages and `--conversation` for named group chats
+- `btx messages send` sends a BTX project chat message from inline text or piped stdin
 - `btx setup` is the first-run path for linking a repo and choosing `codex`, `claude`, or both bootstrap targets
 - Auth is read from `~/.btx/auth-session.json`, with a fallback to the desktop app auth session store
 - Repo linkage is stored in `.btx/btx.json`
@@ -88,6 +95,7 @@ Expected manual npm steps:
 
 - Log in to npm with an account that can publish under `@secondcontext`
 - Set `NPM_TOKEN` in `code/packages/btx-cli/.env` or export it in your shell
-- The publish helper creates a temporary npm user config so workspace-local `.npmrc` files are not needed. Do not run raw `npm publish` from `code/packages/btx-cli`
+- The publish helper in `code/scripts/publish-btx-cli.sh` creates a temporary npm user config so workspace-local `.npmrc` files are not needed. Do not run raw `npm publish` from `code/packages/btx-cli`
+- If `npm run publish:btx-cli:dry-run --prefix code` succeeds but the real publish returns npm `404` for `@secondcontext/btx-cli`, the token is authenticated but does not have publish permission for the package. Fix the npm token or package access instead of retrying raw publish commands
 - Ensure the `@secondcontext` scope is configured for public packages
 - If you want an open-source package, add a real `LICENSE` file before publishing and replace the current `UNLICENSED` marker in `package.json`

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AA4FrD,wBAAsB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAE5E;AAED,wBAAsB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAGnF;AAED,wBAAsB,cAAc,CAAC,CAAC,EACpC,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED,wBAAsB,eAAe,CAAC,CAAC,EACrC,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,CAAC,CAAC,CAGZ"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AA8FrD,wBAAsB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAE5E;AAED,wBAAsB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAGnF;AAED,wBAAsB,cAAc,CAAC,CAAC,EACpC,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED,wBAAsB,eAAe,CAAC,CAAC,EACrC,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,CAAC,CAAC,CAGZ"}

package/dist/api.js

@@ -41,7 +41,7 @@ async function requestWithAuth(env, url, method, body) {
     if (response.status === 401) {
         const refreshed = await refreshAccessToken(env);
         if (!refreshed) {
-            throw new Error('BTX auth token expired. Sign in again through BTX desktop or provide a fresh token.');
+            throw new Error('BTX auth token expired. Run `btx login` to refresh the standalone CLI session, or provide a fresh token.');
         }
         response = await doRequest(refreshed);
     }

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/bin.js

@@ -7,13 +7,27 @@ import { apiGet, projectApiPatch, projectApiPost } from './api.js';
 import { bootstrapAgents } from './bootstrap.js';
 import { clearStoredAuthSession, DEFAULT_API_URL, clearActiveSession, findRepoRoot, getActiveSession, isDesktopFallbackEnabled, loadRepoConfig, resolveRuntimeEnv, resolveStoredAuthSessionSource, setActiveSession, writeRepoConfig, } from './config.js';
 import { loginToBtx } from './login.js';
+import { listChatConversations, listChatMessages, listProjectMembers, resolveMessageScope, sendChatMessage, } from './messages.js';
 import { runRuntimeCli } from './runtime-cli.js';
+const SESSION_CHECKPOINT_TYPES = [
+    'note',
+    'progress',
+    'decision',
+    'risk',
+    'blocker',
+    'assumption',
+    'summary',
+    'question',
+    'next_step',
+];
+const SESSION_CHECKPOINT_USAGE = SESSION_CHECKPOINT_TYPES.join('|');
 const RUNTIME_RESOURCES = new Set([
     'tasks',
     'sessions',
     'contacts',
     'orgs',
     'meetings',
+    'recordings',
     'leads',
     'user',
     'intro-paths',
@@ -69,16 +83,18 @@ Standalone commands:
   btx logout                      Remove stored standalone BTX auth credentials
   btx setup [agent]               Link this repo and bootstrap AGENTS.md and/or CLAUDE.md
   btx projects                    List BTX projects you can access
+  btx ask "<prompt>"              Send a freeform prompt to the general cloud agent
+  btx messages ...                Read and send BTX project chat messages
   btx repo link <project-id>      Link the current repo to a BTX project
   btx repo status                 Show current repo BTX status
   btx bootstrap <agent>           Write BTX instructions into AGENTS.md and/or CLAUDE.md
   btx session start               Start or resume the active BTX coding session for this repo
   btx session status              Show the active BTX coding session
-  btx session checkpoint          Record progress, risk, decision, blocker, or note
+  btx session checkpoint          Record durable session memory: decisions, assumptions, learnings, risks, next steps
   btx session finish              Close the active BTX coding session
 
 BTX resources:
-  tasks, contacts, orgs, leads, meetings, user, intro-paths,
+  tasks, contacts, orgs, leads, meetings, recordings, user, intro-paths,
   search, context, pages, sessions, hiring-types, hiring-candidates
 
 Examples:
@@ -88,17 +104,63 @@ Examples:
   btx setup
   btx setup codex
   btx projects
+  btx ask "Show me a count of tasks by status"
+  btx ask "Who should I follow up with this week?" --trace-tools
+  btx messages list
+  btx messages send "Shipped the fix"
+  btx messages send "Can you review this?" --peer faruk@secondcontext.com
+  btx messages conversations
   btx repo link <project-id>
   btx bootstrap all
   btx context get
+  btx recordings list --days 7
+  btx recordings transcript <recording-id>
+  btx sessions list --limit 10
+  btx sessions get <session-id>
   btx tasks list --json
   btx tasks list
   btx session start --runtime codex --label "Implement project telemetry"
+  btx session checkpoint --type decision --content "Decision: keep desktop and standalone CLI on one contract"
+  btx session checkpoint --type assumption --content "Assumption: users will review saved session intelligence in BTX"
+  btx session checkpoint --type note --content "Learning: product session activities feed long-term project memory"
   btx session checkpoint --type risk --content "Task meaning is still ambiguous across sessions"
   btx session finish --summary "Finished CLI bootstrap and repo linking flow"
 
 All commands that return BTX data support --json for machine-readable output.`);
 }
+function printAskHelp() {
+    console.log(`Usage:
+  btx ask "<prompt>" [--session-id <id>] [--label <label>] [--trace-tools] [--json]
+
+Examples:
+  btx ask "Show me a count of tasks by status"
+  btx ask "What should I focus on next?" --trace-tools
+  btx ask "Continue refining that plan" --session-id <session-id>
+  btx ask --prompt "Summarize our open risks" --json`);
+}
+function printMessagesHelp() {
+    console.log(`Usage:
+  btx messages list [--peer <member>] [--conversation <conversation>] [--limit <n>] [--before <iso>] [--json]
+  btx messages read [--peer <member>] [--conversation <conversation>] [--limit <n>] [--before <iso>] [--json]
+  btx messages send "<body>" [--peer <member>] [--conversation <conversation>] [--reply-to <message-id>] [--json]
+  btx messages members [--json]
+  btx messages conversations [--json]
+
+Scope:
+  no scope flags                 Team chat
+  --peer <member>                Direct messages with a project member
+  --conversation <conversation>  Existing group conversation
+
+Examples:
+  btx messages list
+  btx messages list --peer faruk@secondcontext.com
+  btx messages send "Shipped the fix in main"
+  btx messages send "Can you take a look?" --peer Faruk
+  btx messages send --conversation "Launch planning" "Review the latest blockers"
+  printf "Daily update: validation passed" | btx messages send
+  btx messages members
+  btx messages conversations --json`);
+}
 function bestEffortGitBranch(repoRoot) {
     const result = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
         cwd: repoRoot,
@@ -170,8 +232,14 @@ function printLoginResult(authSource, apiUrl, browserOpened) {
     }
     console.log(`API base: ${apiUrl}`);
 }
-function authStatusPayload() {
-    const env = resolveRuntimeEnv();
+function resolveCliEnv(startDir = process.cwd(), flags = {}, overrides = {}) {
+    return resolveRuntimeEnv(startDir, {
+        ...(flags['api-url'] ? { BTX_API_URL: flags['api-url'] } : {}),
+        ...overrides,
+    });
+}
+function authStatusPayload(flags = {}) {
+    const env = resolveCliEnv(process.cwd(), flags);
     const hasEnvToken = !!process.env.BTX_ACCESS_TOKEN;
     const authSource = hasEnvToken ? 'env' : resolveStoredAuthSessionSource();
     return {
@@ -183,7 +251,7 @@ function authStatusPayload() {
     };
 }
 async function handleProjects(flags) {
-    const env = resolveRuntimeEnv();
+    const env = resolveCliEnv(process.cwd(), flags);
     const projects = await listProjects(env);
     if (isJson(flags)) {
         printJson(projects);
@@ -204,7 +272,7 @@ async function handleProjects(flags) {
 async function handleRepoLink(projectId, flags) {
     if (!projectId)
         die('Usage: btx repo link <project-id>');
-    const env = resolveRuntimeEnv();
+    const env = resolveCliEnv(process.cwd(), flags);
     const projects = await listProjects(env);
     const project = projects.find((item) => item.id === projectId);
     if (!project) {
@@ -265,8 +333,269 @@ function handleRepoStatus(flags) {
         console.log('Active session: none');
     }
 }
+function formatAskToolTrace(toolCalls) {
+    return toolCalls.map((toolCall) => {
+        const status = toolCall.isError ? 'error' : toolCall.status;
+        const input = Object.keys(toolCall.input).length > 0
+            ? ` ${JSON.stringify(toolCall.input)}`
+            : '';
+        return `[${toolCall.kind}:${status}] ${toolCall.name}${input}`;
+    });
+}
+function parsePositiveIntFlag(rawValue, flagName) {
+    if (!rawValue)
+        return undefined;
+    const parsed = Number.parseInt(rawValue, 10);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        die(`\`${flagName}\` must be a positive integer.`);
+    }
+    return parsed;
+}
+function formatTimestamp(value) {
+    const date = new Date(value);
+    if (Number.isNaN(date.valueOf()))
+        return value;
+    return new Intl.DateTimeFormat(undefined, {
+        dateStyle: 'medium',
+        timeStyle: 'short',
+    }).format(date);
+}
+function summarizeText(value, maxLength = 120) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= maxLength)
+        return normalized;
+    return `${normalized.slice(0, maxLength - 1).trimEnd()}…`;
+}
+function printIndentedBlock(value, indent = '  ') {
+    for (const line of value.split(/\r?\n/)) {
+        console.log(`${indent}${line}`);
+    }
+}
+function describeMember(member) {
+    if (member.name && member.email)
+        return `${member.name} <${member.email}>`;
+    return member.name ?? member.email ?? member.userId;
+}
+function describeConversationMember(member) {
+    if (member.name && member.email)
+        return `${member.name} <${member.email}>`;
+    if (member.name)
+        return member.name;
+    if (member.email)
+        return member.email;
+    if (member.externalName && member.externalEmail)
+        return `${member.externalName} <${member.externalEmail}>`;
+    return member.externalName ?? member.externalEmail ?? member.userId ?? 'Unknown member';
+}
+function printMessage(message) {
+    const sender = message.senderName ?? message.senderEmail ?? message.userId;
+    console.log(`${formatTimestamp(message.createdAt)}  ${sender}`);
+    console.log(`  ID: ${message.id}`);
+    if (message.replyTo) {
+        console.log(`  Replying to ${message.replyTo.senderName ?? 'Unknown sender'}: ${summarizeText(message.replyTo.body, 90)}`);
+    }
+    if (message.body.trim()) {
+        printIndentedBlock(message.body);
+    }
+    else if (message.attachments.length > 0) {
+        console.log('  Attachment-only message');
+    }
+    if (message.attachments.length > 0) {
+        console.log(`  Attachments: ${message.attachments.length}`);
+    }
+    if (message.reactions.length > 0) {
+        console.log(`  Reactions: ${message.reactions.map((reaction) => `${reaction.emoji} x${reaction.count}`).join(', ')}`);
+    }
+}
+async function readMessageBody(positionals, flags) {
+    const inlineBody = (flags.body ?? positionals.slice(2).join(' ')).trim();
+    if (inlineBody)
+        return inlineBody;
+    if (!process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+            chunks.push(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+        }
+        const pipedBody = chunks.join('').trim();
+        if (pipedBody)
+            return pipedBody;
+    }
+    return '';
+}
+function printScopeSummary(scope) {
+    console.log(`Scope: ${scope.label}`);
+}
+async function handleAsk(positionals, flags) {
+    if (flags.help === 'true') {
+        printAskHelp();
+        return;
+    }
+    const prompt = (flags.prompt ?? positionals.slice(1).join(' ')).trim();
+    if (!prompt) {
+        printAskHelp();
+        die('Prompt is required.');
+    }
+    const env = resolveCliEnv(process.cwd(), flags);
+    const result = await projectApiPost(env, '/ask', {
+        prompt,
+        ...(flags['session-id'] ? { sessionId: flags['session-id'] } : {}),
+        ...(flags.label ? { label: flags.label } : {}),
+        includeToolTrace: flags['trace-tools'] === 'true',
+    });
+    if (isJson(flags)) {
+        printJson(result);
+        return;
+    }
+    if (result.response) {
+        console.log(result.response);
+    }
+    if (result.question) {
+        if (result.response)
+            console.log();
+        console.log(`Question: ${result.question}`);
+    }
+    if (flags['trace-tools'] === 'true' && result.toolCalls && result.toolCalls.length > 0) {
+        if (result.response || result.question)
+            console.log();
+        console.log('Tools:');
+        for (const line of formatAskToolTrace(result.toolCalls)) {
+            console.log(`  ${line}`);
+        }
+    }
+}
+async function handleMessagesMembers(flags) {
+    const env = resolveCliEnv(process.cwd(), flags);
+    const members = await listProjectMembers(env);
+    if (isJson(flags)) {
+        printJson(members);
+        return;
+    }
+    if (members.length === 0) {
+        console.log('No BTX project members found.');
+        return;
+    }
+    for (const member of members) {
+        console.log(describeMember(member));
+        console.log(`  User ID: ${member.userId}`);
+        console.log(`  Member ID: ${member.id}`);
+        console.log(`  Role: ${member.role}`);
+        console.log(`  Joined: ${formatTimestamp(member.joinedAt)}`);
+        console.log();
+    }
+}
+async function handleMessagesConversations(flags) {
+    const env = resolveCliEnv(process.cwd(), flags);
+    const result = await listChatConversations(env);
+    if (isJson(flags)) {
+        printJson(result);
+        return;
+    }
+    if (result.conversations.length === 0) {
+        console.log('No BTX chat conversations found.');
+        return;
+    }
+    for (const conversation of result.conversations) {
+        console.log(conversation.name);
+        console.log(`  ID: ${conversation.id}`);
+        console.log(`  Created: ${formatTimestamp(conversation.createdAt)}`);
+        if (conversation.members.length > 0) {
+            console.log(`  Members: ${conversation.members.map(describeConversationMember).join(', ')}`);
+        }
+        if (conversation.lastMessage) {
+            const sender = conversation.lastMessage.senderName ?? 'Unknown sender';
+            console.log(`  Last message: ${sender}: ${summarizeText(conversation.lastMessage.body)} (${formatTimestamp(conversation.lastMessage.createdAt)})`);
+        }
+        if (conversation.cursorAt) {
+            console.log(`  Last read: ${formatTimestamp(conversation.cursorAt)}`);
+        }
+        console.log();
+    }
+}
+async function handleMessagesList(flags) {
+    const env = resolveCliEnv(process.cwd(), flags);
+    const scope = await resolveMessageScope(env, {
+        peer: flags.peer,
+        conversation: flags.conversation,
+    });
+    const result = await listChatMessages(env, scope, {
+        before: flags.before,
+        limit: parsePositiveIntFlag(flags.limit, '--limit'),
+    });
+    if (isJson(flags)) {
+        printJson({
+            scope,
+            ...result,
+        });
+        return;
+    }
+    printScopeSummary(scope);
+    if (result.lastReadAt) {
+        console.log(`Last read: ${formatTimestamp(result.lastReadAt)}`);
+    }
+    if (result.messages.length === 0) {
+        console.log('No messages found.');
+        return;
+    }
+    console.log();
+    for (const [index, message] of result.messages.entries()) {
+        printMessage(message);
+        if (index < result.messages.length - 1)
+            console.log();
+    }
+    if (result.hasMore) {
+        console.log();
+        console.log('More messages are available. Use `--before <iso>` to page backward.');
+    }
+}
+async function handleMessagesSend(positionals, flags) {
+    const env = resolveCliEnv(process.cwd(), flags);
+    const scope = await resolveMessageScope(env, {
+        peer: flags.peer,
+        conversation: flags.conversation,
+    });
+    const body = await readMessageBody(positionals, flags);
+    if (!body) {
+        die('Usage: btx messages send "<body>" [--peer <member>] [--conversation <conversation>] [--reply-to <message-id>]');
+    }
+    const result = await sendChatMessage(env, scope, {
+        body,
+        replyToId: flags['reply-to'] ?? null,
+    });
+    if (isJson(flags)) {
+        printJson({
+            ...result,
+            scope,
+            body,
+            replyToId: flags['reply-to'] ?? null,
+        });
+        return;
+    }
+    console.log(`Sent message ${result.id}`);
+    printScopeSummary(scope);
+    console.log(`Created: ${formatTimestamp(result.createdAt)}`);
+}
+async function handleMessages(positionals, flags) {
+    const subcommand = positionals[1];
+    if (flags.help === 'true' || !subcommand || subcommand === 'help') {
+        printMessagesHelp();
+        return;
+    }
+    switch (subcommand) {
+        case 'list':
+        case 'read':
+            return handleMessagesList(flags);
+        case 'send':
+            return handleMessagesSend(positionals, flags);
+        case 'members':
+            return handleMessagesMembers(flags);
+        case 'conversations':
+            return handleMessagesConversations(flags);
+        default:
+            die('Usage: btx messages <list|read|send|members|conversations> [...]');
+    }
+}
 function handleLoginStatus(flags) {
-    const status = authStatusPayload();
+    const status = authStatusPayload(flags);
     if (isJson(flags)) {
         printJson(status);
         return;
@@ -288,9 +617,7 @@ async function handleLogin(positionals, flags) {
     if (subcommand) {
         die('Usage: btx login [status] [flags]');
     }
-    const env = resolveRuntimeEnv(process.cwd(), {
-        ...(flags['api-url'] ? { BTX_API_URL: flags['api-url'] } : {}),
-    });
+    const env = resolveCliEnv(process.cwd(), flags);
     const apiUrl = env.BTX_API_URL || DEFAULT_API_URL;
     const result = await loginToBtx({
         apiUrl,
@@ -392,9 +719,7 @@ async function selectBootstrapTarget(targetArg, flags) {
 }
 async function handleSetup(targetArg, flags) {
     const repoRoot = findRepoRoot();
-    let env = resolveRuntimeEnv(repoRoot, {
-        ...(flags['api-url'] ? { BTX_API_URL: flags['api-url'] } : {}),
-    });
+    let env = resolveCliEnv(repoRoot, flags);
     const loginResult = await loginToBtx({
         apiUrl: env.BTX_API_URL || DEFAULT_API_URL,
         env,
@@ -410,9 +735,7 @@ async function handleSetup(targetArg, flags) {
             }
         },
     });
-    env = resolveRuntimeEnv(repoRoot, {
-        ...(flags['api-url'] ? { BTX_API_URL: flags['api-url'] } : {}),
-    });
+    env = resolveCliEnv(repoRoot, flags);
     let repoConfig = loadRepoConfig(repoRoot);
     let linkedProjectName = repoConfig?.projectName ?? null;
     let linkedProjectId = repoConfig?.projectId ?? null;
@@ -469,7 +792,7 @@ function getCurrentSessionOrDie(repoRoot) {
 }
 async function handleSessionStart(flags) {
     const repoRoot = findRepoRoot();
-    const env = resolveRuntimeEnv(repoRoot);
+    const env = resolveCliEnv(repoRoot, flags);
     const repoConfig = loadRepoConfig(repoRoot);
     if (!repoConfig) {
         die('This repo is not linked to BTX yet. Run `btx repo link <project-id>` first.');
@@ -546,9 +869,12 @@ async function handleSessionCheckpoint(flags) {
     const type = flags.type || 'note';
     const content = flags.content;
     if (!content) {
-        die('Usage: btx session checkpoint --type note|risk|decision|blocker|progress|assumption --content "..."');
+        die(`Usage: btx session checkpoint --type ${SESSION_CHECKPOINT_USAGE} --content "..."`);
+    }
+    if (!SESSION_CHECKPOINT_TYPES.includes(type)) {
+        die(`Unsupported checkpoint type: ${type}. Use one of ${SESSION_CHECKPOINT_USAGE}.`);
     }
-    const env = resolveRuntimeEnv(repoRoot, {
+    const env = resolveCliEnv(repoRoot, flags, {
         BTX_SESSION_ID: active.sessionId,
         BTX_PROJECT_ID: active.projectId,
     });
@@ -571,7 +897,7 @@ async function handleSessionCheckpoint(flags) {
 async function handleSessionFinish(flags) {
     const repoRoot = findRepoRoot();
     const active = getCurrentSessionOrDie(repoRoot);
-    const env = resolveRuntimeEnv(repoRoot, {
+    const env = resolveCliEnv(repoRoot, flags, {
         BTX_SESSION_ID: active.sessionId,
         BTX_PROJECT_ID: active.projectId,
     });
@@ -624,7 +950,7 @@ async function main() {
         return;
     }
     if (RUNTIME_RESOURCES.has(command)) {
-        await runRuntimeCli(argv, resolveRuntimeEnv());
+        await runRuntimeCli(argv, resolveCliEnv(process.cwd(), flags));
         return;
     }
     switch (command) {
@@ -636,6 +962,10 @@ async function main() {
             return handleSetup(positional[1], flags);
         case 'projects':
             return handleProjects(flags);
+        case 'ask':
+            return handleAsk(positional, flags);
+        case 'messages':
+            return handleMessages(positional, flags);
         case 'repo':
             switch (positional[1]) {
                 case 'link':