@zergai/ztc 0.5.0-beta.1 → 0.6.0-beta.1

package/dist/agent/commands/direct_credential_prompt.js

@@ -0,0 +1,422 @@
+import { runOpenAICompatibleWizard } from './openai_compat_wizard.js';
+import { canonicalProvider, DIRECT_PROVIDER_CHOICES, isLocalSubscription } from './provider_choices.js';
+import { compatEndpoint, maskApiKey } from '../../config.js';
+import { ApiKeyEnvNameError, detectApiKeyEnvCandidates, looksLikeApiKey, looksLikeApiKeyEnvName, parseApiKeyEnvName, providerApiKeyEnvNames, readApiKeyEnvReference, readProviderApiKeyEnv, } from '../../config/provider_api_key_env.js';
+const LOCAL_LOGIN_HELP = {
+    claude_code: 'Install Claude Code and sign in with `claude`',
+    codex_app_server: 'Sign in with `codex login`',
+    codex_legacy: 'Sign in with `codex login`',
+    kimi_code: 'Sign in with the Kimi Code CLI',
+};
+/** Providers reached with a pasted API key, as opposed to a local login, an endpoint or the Router. */
+function takesDirectApiKey(provider) {
+    const id = canonicalProvider(provider) ?? provider;
+    return id !== 'openai_compatible' && providerApiKeyEnvNames(id).length > 0;
+}
+/**
+ * Whether a person can answer a secret prompt here. Agent-run commands and
+ * widgets that answer by themselves (headless) cannot.
+ */
+export function canAskForCredential(ctx) {
+    return ctx.commandOrigin !== 'agent' && Boolean(ctx.prompt?.showPrompt) && ctx.prompt.interactive !== false;
+}
+export function providerLabel(provider) {
+    return DIRECT_PROVIDER_CHOICES.find(choice => choice.id === provider)?.label ?? provider;
+}
+/**
+ * What else decides which key `provider` uses, so a key just saved is never
+ * silently ignored. Names variables, never their values.
+ */
+export function savedKeyNotes(provider, stored, ctx) {
+    if (ctx.config.getApiKey(provider) !== stored) {
+        const source = ctx.config.getApiKeySource(provider);
+        return [source.kind === 'env-ref'
+                ? `  ⚠ This session reads the ${provider} key from $${source.name}, so the saved key is not used. Clear it with /config scope clear.`
+                : `  ⚠ This session uses a different ${provider} key, so the saved key is not used. Clear it with /config scope clear.`];
+    }
+    const standard = readProviderApiKeyEnv(provider);
+    return standard ? [`  $${standard.name} is also set; ZTC uses the saved key.`] : [];
+}
+/**
+ * Ask for a direct provider's missing credential: paste an API key, name the
+ * environment variable that holds it, or cancel. The one owner of this
+ * interaction for every selection command, /connect direct and the composer.
+ * Local logins get sign-in help and a custom endpoint gets its setup form.
+ * Nothing is saved until the person confirms a key or a variable, so Cancel
+ * or Escape at any step leaves the config as it was.
+ *
+ * Returns false without asking when nobody can answer (an agent-run command or
+ * headless widgets) or the provider takes no key, so the caller prints its own
+ * message. `onReady` runs once the provider has a usable key.
+ */
+export function promptForDirectCredential(provider, ctx, onReady, options = {}) {
+    if (!canAskForCredential(ctx))
+        return false;
+    const id = canonicalProvider(provider) ?? provider;
+    if (isLocalSubscription(id)) {
+        ctx.addMessage({ role: 'system', content: `${LOCAL_LOGIN_HELP[id] ?? 'Sign in with the provider CLI'}, then try again. Switchable accounts: /accounts.` });
+        return true;
+    }
+    if (id === 'openai_compatible') {
+        options.beforeAsk?.();
+        // A saved endpoint is ready to select, as a saved key is; a cancel steps back.
+        runOpenAICompatibleWizard(ctx, saved => (saved ? onReady() : options.onCancel?.()));
+        return true;
+    }
+    if (!takesDirectApiKey(id))
+        return false;
+    options.beforeAsk?.();
+    offerChoices(startRequest(id, ctx, onReady, options.onCancel));
+    return true;
+}
+/**
+ * The prompt for a resolved route that cannot build. Only a direct route whose
+ * provider takes a key qualifies; a Router route needs a login instead.
+ */
+export function promptForMissingDirectKey(resolved, ctx, onReady, options = {}) {
+    if (resolved.useProxy || resolved.authMode === 'zrouter' || !takesDirectApiKey(resolved.provider))
+        return false;
+    return promptForDirectCredential(resolved.provider, ctx, onReady, options);
+}
+/**
+ * A provider's key choices, as its key row in /config and `/config key
+ * <provider>` offer them: paste a key, name an environment variable, stop
+ * reading a variable or remove the saved key, or cancel. `onDone` runs once,
+ * with the change made or undefined when nothing changed. False, without
+ * asking, when nobody can answer here or the provider takes no API key.
+ */
+export function manageApiKey(provider, ctx, onDone, options = {}) {
+    if (!canAskForCredential(ctx))
+        return false;
+    const id = canonicalProvider(provider) ?? provider;
+    if (!takesDirectApiKey(id))
+        return false;
+    options.beforeAsk?.();
+    offerChoices(manageRequest(id, ctx, onDone));
+    return true;
+}
+/**
+ * `/config key <provider> NAME`: read the key from the variable NAME, as the
+ * variable choice would. False, without asking, when nobody can answer here.
+ */
+export async function useApiKeyVariable(provider, name, ctx, onDone) {
+    if (!canAskForCredential(ctx))
+        return false;
+    const id = canonicalProvider(provider) ?? provider;
+    if (!takesDirectApiKey(id))
+        return false;
+    await handleVariableName(manageRequest(id, ctx, onDone), name);
+    return true;
+}
+/** A key ZTC can remove: one it saved, or a variable named for it. */
+export function hasRemovableKey(source) {
+    return source.kind === 'saved' || source.kind === 'env-ref';
+}
+/**
+ * `/config key <provider> --remove`: stop reading the variable named for the
+ * key, or forget the saved key, as the key row's remove choice does, without
+ * a question. A custom endpoint's key goes everywhere at once (see removeKey).
+ * Says so when there is nothing to remove; agents cannot use it.
+ */
+export async function removeApiKey(provider, ctx, onDone) {
+    const id = canonicalProvider(provider) ?? provider;
+    const endpoint = id === 'openai_compatible';
+    if (ctx.commandOrigin === 'agent') {
+        ctx.addMessage({ role: 'system', content: `Remove the ${endpoint ? "custom endpoint's" : providerLabel(id)} key from /keys in your session.` });
+        return;
+    }
+    const source = ctx.config.getApiKeySource(id);
+    if (!hasRemovableKey(source)) {
+        const standard = source.kind === 'env-default' ? ` ZTC reads $${source.name} from your environment.` : '';
+        ctx.addMessage({ role: 'system', content: `${endpoint ? 'The custom endpoint' : providerLabel(id)} has no saved key or variable to remove.${standard}` });
+        return;
+    }
+    await removeKey(manageRequest(id, ctx, onDone));
+}
+function startRequest(provider, ctx, onReady, onCancel) {
+    const scope = ctx.config.getConfigScope?.();
+    return {
+        provider, label: providerLabel(provider), ctx, onReady, onCancel,
+        inScope: async (step) => {
+            if (scope && ctx.config.withConfigScope)
+                await ctx.config.withConfigScope(scope, step);
+            else
+                await step();
+        },
+    };
+}
+function manageRequest(provider, ctx, onDone) {
+    return { ...startRequest(provider, ctx, onDone, () => onDone()), onChanged: onDone };
+}
+/** The key a provider uses when no variable is named for it, in words. */
+function fallbackText(source) {
+    const fallback = source.kind === 'env-ref' ? source.fallback : source;
+    if (fallback?.kind === 'saved')
+        return 'the saved key';
+    if (fallback?.kind === 'env-default')
+        return `$${fallback.name}`;
+    return undefined;
+}
+/**
+ * The choices for getting a key. A missing key asks for one; the key row
+ * (`onChanged` set) can also replace or remove what is configured. A variable
+ * named but not set is shown, with choices to fix its name or stop reading it.
+ */
+function offerChoices(request) {
+    const { provider, label, ctx } = request;
+    const manage = Boolean(request.onChanged);
+    const source = ctx.config.getApiKeySource(provider);
+    const reference = source.kind === 'env-ref' ? source : undefined;
+    const dangling = reference && !reference.set ? reference.name : undefined;
+    const detected = detectApiKeyEnvCandidates(provider);
+    const standard = providerApiKeyEnvNames(provider);
+    const keySaved = source.kind === 'saved' || reference?.fallback?.kind === 'saved';
+    const options = [
+        { value: 'paste', label: manage && keySaved ? 'Replace the saved key' : 'Paste an API key',
+            description: 'Hidden input · saved in your ZTC config' },
+        dangling
+            ? { value: 'env', label: 'Fix the variable name', description: `Edit $${dangling}, or name another variable` }
+            : { value: 'env', label: 'Use an environment variable',
+                description: `Standard: ${standard.join(' or ')}${detected.length > 0 ? ` · set now: ${detected.join(', ')}` : ''}` },
+        ...(reference
+            ? [{ value: 'remove', label: `Stop reading $${reference.name}`, description: reference.fallback
+                        ? `ZTC uses ${fallbackText(source)} instead` : 'ZTC forgets the variable name; the variable itself is untouched' }]
+            : manage && source.kind === 'saved'
+                ? [{ value: 'remove', label: 'Remove the saved key', description: 'Delete it from your ZTC config' }]
+                : []),
+        { value: 'cancel', label: 'Cancel', description: manage ? 'Keep things as they are' : 'Keep the current selection' },
+    ];
+    ctx.select.showSelect({ title: manage ? `${label} API key` : `${label} needs an API key`,
+        question: dangling ? `$${dangling} is not set. How should ZTC get your ${label} API key?`
+            : `How should ZTC get your ${label} API key?`,
+        type: 'select', options, compact: true }, async (value) => {
+        if (value === 'paste')
+            return askForKey(request);
+        if (value === 'env')
+            return askForVariable(request, dangling);
+        if (value === 'remove' && options.some(option => option.value === 'remove'))
+            return removeKey(request);
+        // Escape is announced by the widget; an explicit Cancel is confirmed here.
+        if (value === 'cancel')
+            ctx.addMessage({ role: 'system', content: 'Cancelled.' });
+        await request.onCancel?.();
+    });
+}
+/** What removing a custom endpoint's key did. */
+function endpointRemovalSummary(source) {
+    if (source.kind !== 'env-ref')
+        return "✓ Removed the custom endpoint's key.";
+    return source.fallback?.kind === 'saved'
+        ? `✓ Removed the custom endpoint's key and stopped reading $${source.name}.`
+        : `✓ The custom endpoint no longer reads $${source.name}.`;
+}
+/**
+ * What a custom endpoint does once its key is removed. `keyNote` says which
+ * other key it reads, if any; without one, local servers need none. Its extra
+ * headers stay, and one can carry a key of its own, so they are named; their
+ * values never show.
+ */
+function endpointKeyNote(ctx, keyNote) {
+    const settings = ctx.config.getOpenAICompatibleSettings?.();
+    const headers = Object.keys(settings?.headers ?? {}).join(', ');
+    const kept = headers ? ` Its extra headers (${headers}) stay; edit the endpoint to change them.` : '';
+    const baseUrl = settings?.baseUrl;
+    if (keyNote !== undefined || !baseUrl)
+        return `${keyNote ?? ''}${kept}`;
+    const accepted = (apiKey) => {
+        try {
+            compatEndpoint(baseUrl, { apiKey });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (accepted()) {
+        return headers ? ` ZTC now calls ${baseUrl} with only its extra headers (${headers}); edit the endpoint to change them.`
+            : ` ZTC now calls ${baseUrl} without a key; local servers such as Ollama need none.`;
+    }
+    // A remote endpoint is refused without a key; an endpoint refused either way is not about the key.
+    // The endpoint form takes the key in a hidden field; one typed after a command shows in the composer.
+    return accepted('key') ? ` ZTC needs a key for the remote endpoint ${baseUrl}; set it in Custom endpoint… in /keys.${kept}` : kept;
+}
+/**
+ * Stop reading the variable named for the key, or forget the saved key. A
+ * custom endpoint's key is one thing to its owner, though it is saved in two
+ * places and may be named by a variable, so all of it goes at once.
+ */
+async function removeKey(request) {
+    const { provider, label, ctx } = request;
+    const endpoint = provider === 'openai_compatible';
+    await request.inScope(async () => {
+        const source = ctx.config.getApiKeySource(provider);
+        // Stopping a variable keeps the saved key it stood in front of.
+        if (source.kind === 'env-ref' && !endpoint)
+            ctx.config.setApiKeyEnv(undefined, provider);
+        else
+            ctx.config.clearApiKey(provider);
+        await ctx.config.save();
+        const summary = endpoint ? endpointRemovalSummary(source)
+            : source.kind === 'env-ref' ? `✓ ${label} no longer reads $${source.name}.`
+                : `✓ Removed the saved ${label} API key.`;
+        const after = ctx.config.getApiKeySource(provider);
+        const keyNote = after.kind === 'env-default' ? ` ZTC now reads $${after.name} from your environment.`
+            : after.kind === 'saved' ? ' ZTC uses the saved key.' : undefined;
+        const note = endpoint ? endpointKeyNote(ctx, keyNote) : keyNote ?? '';
+        ctx.addMessage({ role: 'system', content: `${summary}${note}` });
+        const change = { kind: 'removed', summary };
+        if (request.onChanged)
+            return request.onChanged(change);
+        // Asked for a missing key: the provider still needs one.
+        if (ctx.config.getApiKey(provider))
+            return request.onReady(change);
+        offerChoices(request);
+    });
+}
+function askForKey(request) {
+    const { label, ctx } = request;
+    ctx.prompt.showPrompt({
+        title: `${label} API key`, question: `Paste your ${label} API key (input is hidden):`,
+        isPassword: true, allowEmptySubmit: false,
+    }, async (value) => {
+        const key = value?.trim();
+        if (!key) {
+            if (value !== null)
+                ctx.addMessage({ role: 'system', content: 'No key entered; nothing changed.' });
+            await request.onCancel?.();
+            return;
+        }
+        // A variable name typed here is read as one; it is never saved as the key.
+        if (looksLikeApiKeyEnvName(key))
+            return handleVariableName(request, key);
+        await saveKey(request, key);
+    });
+}
+async function saveKey(request, key) {
+    const { provider, label, ctx } = request;
+    await request.inScope(async () => {
+        ctx.config.setApiKey(key, provider);
+        await ctx.config.save();
+        ctx.addMessage({ role: 'system', content: [
+                `✓ Saved your ${label} API key (${maskApiKey(key)}) to ${ctx.config.locationLabel || '~/.ztc/config.json'}.`,
+                ...savedKeyNotes(provider, key, ctx),
+            ].join('\n') });
+        await request.onReady({ kind: 'saved', summary: `✓ Saved your ${label} API key (${maskApiKey(key)}).` });
+    });
+}
+/** Ask for the variable that holds the key; `name` fills the field to fix a name. */
+function askForVariable(request, name) {
+    const { provider, label, ctx } = request;
+    const standard = providerApiKeyEnvNames(provider)[0];
+    ctx.prompt.showPrompt({
+        // The prompt box is narrow, so the question stays short and names the standard variable.
+        title: `${label} API key variable`,
+        question: `Variable name (Enter for ${standard}):`,
+        placeholder: standard, defaultValue: name ?? detectApiKeyEnvCandidates(provider)[0],
+        // An empty field means the standard name it shows.
+        isPassword: false, allowEmptySubmit: true,
+        // A key pasted here by mistake shows as dots.
+        maskWhen: looksLikeApiKey,
+    }, async (value) => {
+        if (value === null) {
+            await request.onCancel?.();
+            return;
+        }
+        await handleVariableName(request, value.trim() || standard);
+    });
+}
+/**
+ * Use the variable the person named. A set variable is saved by name; an
+ * unset one is saved only if the person says so. Input that is not a usable
+ * name is refused without repeating it: it may be a key.
+ */
+async function handleVariableName(request, input) {
+    const { provider, label, ctx } = request;
+    if (looksLikeApiKey(input))
+        return offerToSaveAsKey(request, input.trim());
+    let name;
+    try {
+        name = parseApiKeyEnvName(input, provider);
+    }
+    catch (error) {
+        if (!(error instanceof ApiKeyEnvNameError))
+            throw error;
+        ctx.addMessage({ role: 'system', content: error.message });
+        return offerChoices(request);
+    }
+    if (readApiKeyEnvReference(name, provider) === undefined)
+        return offerUnsetVariable(request, name);
+    await request.inScope(async () => {
+        ctx.config.setApiKeyEnv(name, provider);
+        await ctx.config.save();
+        ctx.addMessage({ role: 'system', content: `✓ ${label} reads its API key from $${name}. Saved the variable name, not its value.` });
+        await request.onReady({ kind: 'env', summary: `✓ ${label} reads its API key from $${name}.` });
+    });
+}
+/** A key typed where a variable name was asked for: never shown, saved only as the key. */
+function offerToSaveAsKey(request, key) {
+    const { label, ctx } = request;
+    ctx.addMessage({ role: 'system', content: 'That looks like an API key, not a variable name, so ZTC did not show or save it.' });
+    ctx.select.showSelect({
+        title: `Save it as your ${label} key?`, type: 'select',
+        question: 'Save what you entered as the API key, or type a variable name?',
+        options: [
+            { value: 'save', label: `Save it as the ${label} API key`, description: 'Saved in your ZTC config · never shown' },
+            { value: 'env', label: 'Type a variable name instead' },
+            { value: 'cancel', label: 'Cancel', description: 'Nothing is saved' },
+        ],
+        compact: true,
+    }, async (value) => {
+        if (value === 'save')
+            return saveKey(request, key);
+        if (value === 'env')
+            return askForVariable(request);
+        if (value === 'cancel')
+            ctx.addMessage({ role: 'system', content: 'Cancelled.' });
+        await request.onCancel?.();
+    });
+}
+/** A valid variable name that is not set in this process: fix it, paste a key, or save it anyway. */
+function offerUnsetVariable(request, name) {
+    const { provider, label, ctx } = request;
+    const fallback = fallbackText(ctx.config.getApiKeySource(provider));
+    ctx.select.showSelect({
+        title: `$${name} is not set`, type: 'select',
+        question: `$${name} is not set in this ZTC process. ZTC sees only variables exported before it started.`,
+        options: [
+            { value: 'env', label: 'Fix the variable name', description: `Edit $${name}` },
+            { value: 'paste', label: 'Paste an API key instead', description: 'Hidden input · saved in your ZTC config' },
+            { value: 'save', label: "Save it anyway (I'll export it and restart ZTC)",
+                description: fallback ? `Until then ZTC uses ${fallback}` : `Until then ${label} has no key` },
+            { value: 'cancel', label: 'Cancel', description: 'Nothing changes' },
+        ],
+        compact: true,
+    }, async (value) => {
+        if (value === 'env')
+            return askForVariable(request, name);
+        if (value === 'paste')
+            return askForKey(request);
+        if (value === 'save')
+            return saveUnsetVariable(request, name);
+        if (value === 'cancel')
+            ctx.addMessage({ role: 'system', content: 'Cancelled.' });
+        await request.onCancel?.();
+    });
+}
+/** Save a variable that is not set yet; the provider keeps any key it had until it is. */
+async function saveUnsetVariable(request, name) {
+    const { provider, label, ctx } = request;
+    await request.inScope(async () => {
+        ctx.config.setApiKeyEnv(name, provider);
+        await ctx.config.save();
+        const fallback = fallbackText(ctx.config.getApiKeySource(provider));
+        const summary = `✓ Saved $${name} for ${label}. Export it and restart ZTC to use it.`;
+        ctx.addMessage({ role: 'system', content: `${summary} Until then ${fallback ? `ZTC uses ${fallback}` : `${label} has no key`}.` });
+        const change = { kind: 'env-pending', summary };
+        if (request.onChanged)
+            return request.onChanged(change);
+        if (ctx.config.getApiKey(provider))
+            return request.onReady(change);
+        await request.onCancel?.();
+    });
+}

package/dist/agent/commands/effort.d.ts

@@ -2,4 +2,5 @@
 import { Command } from './types.js';
 export declare const effortCommand: Command;
 export declare const thinkingCommand: Command;
+export declare const reasoningCommand: Command;
 export declare const fastCommand: Command;

package/dist/agent/commands/effort.js

@@ -1,29 +1,14 @@
 import { CODEX_REASONING_EFFORTS } from '../../config/types.js';
-import { resolveCodexEffort } from '../../config/defaults.js';
-import { getSupportedCodexReasoningEfforts } from '../../utils/models.js';
-import { formatReasoningEffort, parseReasoningSelection, reasoningCommandChoices } from '../../utils/reasoning.js';
-import { resolveRouterModel } from '../../utils/router_catalog.js';
+import { parseReasoningSelection, reasoningCommandChoices } from '../../utils/reasoning.js';
+import { offerReasoningPicker } from './reasoning_picker.js';
+import { activeReasoning, applyModelEffort } from './reasoning_settings.js';
 async function configureReasoning(kind, args, ctx) {
-    const config = ctx.config.get();
-    const provider = ctx.config.getProvider?.() || config.provider || 'anthropic';
-    const model = ctx.config.getModel?.() || config.model;
-    const surface = ctx.config.getReasoningWireSurface?.(provider, model)
-        ?? (config.authMode === 'zrouter' || provider === 'openai_compatible' ? 'chat_tools' : 'native_api');
-    const catalog = ctx.config.getRoutedModelCatalog?.();
-    const capabilities = catalog?.version === 1 ? resolveRouterModel(catalog, provider, model)?.capabilities : undefined;
-    const current = resolveCodexEffort(config, provider, model, capabilities ?? surface);
-    const supported = catalog?.version === 1 ? capabilities?.reasoning?.choices ?? [] : getSupportedCodexReasoningEfforts(model, provider, surface);
-    const contract = ctx.config.getReasoningContract?.(provider, model)
-        ?? (catalog?.version === 1 ? capabilities?.reasoning ?? [] : surface);
+    // Without an argument a person chooses in the picker; the agent, headless runs
+    // and models without levels get the readout below.
+    if (args.length === 0 && offerReasoningPicker(ctx))
+        return;
+    const { provider, model, contract, supported, current, status } = activeReasoning(ctx);
     const thinkingChoices = reasoningCommandChoices('thinking', provider, model, contract);
-    const status = () => {
-        const effective = resolveCodexEffort(ctx.config.get(), provider, model, capabilities ?? surface);
-        // A startup flag is this process's value, never the saved default, so say
-        // where an effort that came from one is coming from.
-        const processEffort = ctx.config.getCodexEffortOverride?.();
-        return `Reasoning effort (${provider} · ${model}): ${formatReasoningEffort(effective)}`
-            + (processEffort ? ' (from a startup flag, this process)' : '');
-    };
     if (args.length === 0) {
         ctx.addMessage({ role: 'system', content: status() +
                 (supported?.length === 0 ? '\nThis model does not support a reasoning-effort setting.' :
@@ -43,26 +28,23 @@ async function configureReasoning(kind, args, ctx) {
         ctx.addMessage({ role: 'system', content: error.message });
         return;
     }
-    ctx.config.setModelEffort(model, level);
-    // The startup flag is this instance's starting value, not a lock: an explicit
-    // choice replaces it for the rest of the process.
-    ctx.config.clearCodexEffortOverride?.();
-    await ctx.config.save();
-    ctx.reloadAgent();
-    ctx.addMessage({ role: 'system', content: level === null
-            ? `Model effort override cleared. ${status()}`
-            : `Reasoning effort for ${provider} · ${model} set to "${formatReasoningEffort(level)}".` });
+    await applyModelEffort(ctx, level);
 }
 export const effortCommand = {
-    name: 'effort', description: 'Show or set reasoning effort for the active provider/model',
+    name: 'effort', description: 'Choose reasoning effort and thinking for the active model, or set a level',
     usage: '[none|minimal|low|medium|high|xhigh|max|ultra|default]', category: 'config',
     handler: (args, ctx) => configureReasoning('effort', args, ctx),
 };
 export const thinkingCommand = {
-    name: 'thinking', description: 'Show reasoning settings or turn thinking on/off for the active model',
+    name: 'thinking', description: 'Choose reasoning effort and thinking for the active model, or turn thinking on or off',
     usage: '[on|off]', category: 'config',
     handler: (args, ctx) => configureReasoning('thinking', args, ctx),
 };
+export const reasoningCommand = {
+    name: 'reasoning', description: 'Choose reasoning effort and thinking for the active model',
+    usage: '[level|on|off|default]', category: 'config',
+    handler: (args, ctx) => configureReasoning(args.length === 1 && /^(on|off)$/i.test(args[0]) ? 'thinking' : 'effort', args, ctx),
+};
 export const fastCommand = {
     name: 'fast',
     description: 'Toggle Codex/GPT fast mode (priority service tier for lower latency)',

package/dist/agent/commands/goal.d.ts

@@ -405,10 +405,6 @@ export interface GoalClock {
  * Scans only assistant turn text — never the injected continuation prompt.
  */
 export declare function detectGoalCompletion(text: string | null | undefined): boolean;
-/**
- * Parse `/goal` set-mode args into an objective plus optional --budget /
- * --max-turns flags. Returns `{ error }` for empty objectives or bad numbers.
- */
 export declare function parseGoalArgs(args: string[]): {
     objective: string;
     tokenBudget?: number;

package/dist/agent/commands/goal.js

@@ -410,6 +410,7 @@ export function detectGoalCompletion(text) {
  * Parse `/goal` set-mode args into an objective plus optional --budget /
  * --max-turns flags. Returns `{ error }` for empty objectives or bad numbers.
  */
+const SUSTAINED_GOAL_FLAGS = new Set(['--budget', '--tokens', '--max-turns', '--turns', '--max', '--plateau', '--benchmark-scope', '--min-improvement-percent']);
 export function parseGoalArgs(args) {
     const objectiveTokens = [];
     let tokenBudget;
@@ -424,6 +425,20 @@ export function parseGoalArgs(args) {
         const flag = eq >= 0 ? tok.slice(0, eq) : tok;
         const inlineVal = eq >= 0 ? tok.slice(eq + 1) : undefined;
         const lower = flag.toLowerCase();
+        const numericFlag = lower === '--budget' || lower === '--tokens' || lower === '--max-turns'
+            || lower === '--turns' || lower === '--max' || lower === '--plateau'
+            || lower === '--min-improvement-percent';
+        const scopeFlag = lower === '--benchmark-scope';
+        const nextArg = i + 1 < args.length ? args[i + 1] : undefined;
+        const hasInline = inlineVal !== undefined;
+        const trailingValue = nextArg != null && i + 2 === args.length && !nextArg.startsWith('--');
+        const numericValueOk = numericFlag
+            && (hasInline || trailingValue || (nextArg != null && /^-?\d[\d_,]*$/.test(nextArg)) || i + 1 >= args.length);
+        const scopeValueOk = scopeFlag && (hasInline || (nextArg != null && !nextArg.startsWith('--')));
+        if ((numericFlag || scopeFlag) && !numericValueOk && !scopeValueOk) {
+            objectiveTokens.push(tok);
+            continue;
+        }
         if (lower === '--plateau') {
             attempts = parsePositiveInt(inlineVal ?? args[++i]) ?? undefined;
             if (attempts === undefined || attempts > 32)
@@ -463,21 +478,25 @@ export function parseGoalArgs(args) {
             maxTurns = parsed;
             continue;
         }
-        if (lower.startsWith('--')) {
-            return { error: `Unknown flag "${flag}". Supported: --budget <n>, --max-turns <n>.` };
+        // Flag-like words are objective text, but a mistyped option given a number
+        // would silently drop the budget or turn cap it was meant to set.
+        const value = inlineVal ?? nextArg;
+        if (lower.startsWith('--') && value !== undefined && /^-?\d[\d_,]*$/.test(value)) {
+            const intended = nearGoalFlag(lower);
+            if (intended)
+                return { error: `Unknown flag "${flag}". Did you mean ${intended}?` };
         }
         objectiveTokens.push(tok);
     }
     const objective = objectiveTokens.join(' ').trim();
     if (!objective)
         return { error: 'Usage: /goal <objective>  [--budget <tokens>] [--max-turns <n>]' };
-    // The objective is echoed into every continuation prompt; an embedded sentinel
-    // would let the goal complete or block itself the moment the agent restates it.
-    if (/goal[ _]?complete/i.test(objective)) {
-        return { error: `Objective must not contain "${GOAL_COMPLETE_SENTINEL}" — that token is reserved to signal completion.` };
-    }
-    if (/goal[ _]?blocked/i.test(objective)) {
-        return { error: `Objective must not contain "${GOAL_BLOCKED_SENTINEL}" — that token is reserved to signal a stalled goal.` };
+    for (const line of objective.split(/\r?\n/)) {
+        const bare = line.trim().replace(/^[`*_>#~\s-]+/, '').replace(/[`*_~\s]+$/, '');
+        // The same test detectGoalCompletion and detectGoalBlocked apply to a line.
+        if (/^goal[ _]complete\b/i.test(bare) || /^goal[ _]blocked\b/i.test(bare)) {
+            return { error: 'Objective must not contain a bare completion or blocked sentinel line — that token is reserved to signal completion.' };
+        }
     }
     const plateau = attempts === undefined ? undefined : parseGoalPlateauCriteria({ scope: benchmarkScope, attempts, minImprovementPercent });
     if ((attempts !== undefined && !plateau) || (attempts === undefined && (benchmarkScope !== undefined || hasThreshold))) {
@@ -485,6 +504,22 @@ export function parseGoalArgs(args) {
     }
     return { objective, ...(tokenBudget != null ? { tokenBudget } : {}), ...(maxTurns != null ? { maxTurns } : {}), ...(plateau ? { plateau } : {}) };
 }
+/** The supported flag at most two edits from an unknown one, if any. */
+function nearGoalFlag(flag) {
+    for (const known of SUSTAINED_GOAL_FLAGS) {
+        let previous = Array.from({ length: known.length + 1 }, (_, index) => index);
+        for (let i = 1; i <= flag.length; i++) {
+            const current = [i];
+            for (let j = 1; j <= known.length; j++) {
+                current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, previous[j - 1] + (flag[i - 1] === known[j - 1] ? 0 : 1));
+            }
+            previous = current;
+        }
+        if (previous[known.length] <= 2)
+            return known;
+    }
+    return undefined;
+}
 function parsePositiveInt(raw) {
     if (raw == null)
         return null;
@@ -783,7 +818,10 @@ export class GoalManager {
         if (!/\b(?:keep|continue)\s+(?:working|iterating|optimizing|doing|going)\b/iu.test(text)
             || !/\buntil\b[\s\S]*\b(?:interrupt|stop|done|complete|plateau)\b/iu.test(text) || text.length > MAX_OBJECTIVE_LEN)
             return null;
-        const parsed = parseGoalArgs(text.split(/\s+/u));
+        const tokens = text.split(/[^\S\n]+/u);
+        if (tokens.some(token => token.startsWith('--') && !SUSTAINED_GOAL_FLAGS.has(token.split('=')[0].toLowerCase())))
+            return null;
+        const parsed = parseGoalArgs(tokens);
         if ('error' in parsed)
             return null;
         const statedBudgets = [...text.matchAll(/\b(?:budget(?: of)?|limit(?: (?:total )?(?:token )?usage)? to|within|up to)\s+([\d,_]+)\s+tokens\b/giu)]

package/dist/agent/commands/handoff.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from './types.js';
+/**
+ * `/handoff` — the saved task checkpoint this session resumed from, in full.
+ * A resumed launch announces it in two lines; this is where the rest lives.
+ */
+export declare const handoffCommand: Command;

package/dist/agent/commands/handoff.js

@@ -0,0 +1,17 @@
+import { formatTaskHandoffSummary } from '../../session_handoff_contract.js';
+/**
+ * `/handoff` — the saved task checkpoint this session resumed from, in full.
+ * A resumed launch announces it in two lines; this is where the rest lives.
+ */
+export const handoffCommand = {
+    name: 'handoff',
+    description: 'Show the saved task checkpoint this session resumed from',
+    usage: '/handoff',
+    handler: async (_args, ctx) => {
+        const projection = ctx.getTaskHandoff?.() ?? null;
+        ctx.addMessage({
+            role: 'system',
+            content: projection ? formatTaskHandoffSummary(projection.snapshot) : 'No saved task checkpoint in this session.',
+        });
+    },
+};

package/dist/agent/commands/help.js

@@ -16,7 +16,7 @@ export function makeHelpCommand(getCommands) {
                 .join('\n\n');
             ctx.addMessage({
                 role: 'system',
-                content: `${buildHelpIntroduction()}\n\nKeyboard actions:\n  Esc twice within 2 seconds confirms stop of the running turn.\n  In the queue editor (Option+Up), Esc removes only the selected queued message.\n  Forms, choices and completions close with one Esc; idle Esc keeps the draft and queue.\n  /rewind opens the Ratatui history picker; Ctrl+B ? opens zmux shortcut help.\n\nMouse and scrolling:\n  /settings mouseCapture toggles terminal mouse capture.\n  /settings wheelScrollLines sets 1–20 lines per wheel event (default 3).\n  These preferences require a compatible native renderer; otherwise they are saved for the next compatible launch.\n\nStatus line fields:\n${statusHelp}\n\nAvailable commands:\n\n${helpText || '  No commands registered.'}`
+                content: `${buildHelpIntroduction()}\n\nKeyboard actions:\n  Esc twice within 2 seconds confirms stop of the running turn.\n  In the queue editor (Option+Up), Esc removes only the selected queued message.\n  Forms, choices and completions close with one Esc; one idle Esc keeps the draft and queue.\n  Esc twice while idle opens the rewind picker, as /rewind does; Ctrl+B ? opens zmux shortcut help.\n\nMouse and scrolling:\n  /settings mouseCapture toggles terminal mouse capture.\n  /settings wheelScrollLines sets 1–20 lines per wheel event (default 3).\n  These preferences require a compatible native renderer; otherwise they are saved for the next compatible launch.\n\nStatus line fields:\n${statusHelp}\n\nAvailable commands:\n\n${helpText || '  No commands registered.'}`
             });
         }
     };