@sayknow-cli/coding-agent 0.3.6 → 0.3.8

package/src/append-only-mode.ts

@@ -0,0 +1,58 @@
+/**
+ * Single source of truth for append-only context-mode resolution and manager
+ * construction. Both the initial session build (`sdk.ts`) and the runtime
+ * model/setting-change path (`agent-session.ts`), plus the status UI, resolve
+ * through here so the auto allowlist and prefix-reset diagnostics never drift.
+ */
+
+import { AppendOnlyContextManager } from "@sayknow-cli/agent-core";
+import { logger } from "@sayknow-cli/utils";
+
+/**
+ * Providers for which append-only context auto-enables. Exact provider-string
+ * match only: `anthropic` reached via a gateway/aggregator provider string
+ * (e.g. `openrouter`, a custom gateway) does NOT match and stays opt-in via
+ * `provider.appendOnlyContext: "on"`, because those transports can rewrite or
+ * renormalize the request in ways that have not been validated for append-only
+ * prefix stability.
+ */
+export function providerSupportsAppendOnlyAuto(provider: string): boolean {
+	return provider === "deepseek" || provider === "anthropic";
+}
+
+/**
+ * Resolve whether to enable append-only context mode based on the setting and provider.
+ *
+ * - `"on"` → always enable
+ * - `"off"` → never enable
+ * - `"auto"` → enable for providers with strong prompt-prefix caching that this
+ *   harness has validated (see {@link providerSupportsAppendOnlyAuto})
+ */
+export function resolveAppendOnlyMode(setting: "auto" | "on" | "off" | undefined, provider: string): boolean {
+	switch (setting ?? "auto") {
+		case "on":
+			return true;
+		case "off":
+			return false;
+		default:
+			return providerSupportsAppendOnlyAuto(provider);
+	}
+}
+
+/**
+ * Construct an {@link AppendOnlyContextManager} wired to emit per-session
+ * stable-prefix reset diagnostics. Use this at every creation site so the
+ * telemetry is uniform.
+ */
+export function createAppendOnlyContextManager(provider: string | undefined): AppendOnlyContextManager {
+	return new AppendOnlyContextManager({
+		onPrefixChange: info =>
+			logger.debug("append-only stable prefix changed (cache prefix reset)", {
+				provider,
+				from: info.from,
+				to: info.to,
+				version: info.version,
+				reason: info.from === "<unbuilt>" ? "initial-build" : "prefix-mutation",
+			}),
+	});
+}

package/src/autoresearch/prompt.md

@@ -22,7 +22,7 @@ You are running an autonomous experiment loop. Keep iterating until the user int
 ### Available tools
 - `init_experiment` — open or reconfigure the session. Pass `new_segment: true` to start a fresh baseline within the current session.
 - `run_experiment` — run the benchmark (`bash autoresearch.sh`). Output is captured automatically and `METRIC name=value` / `ASI key=value` lines printed by the harness are parsed back to you. The command is fixed; if you need a different workload, edit `autoresearch.sh` and bump segment via `init_experiment new_segment: true`.
-- `log_experiment` — record the result. On `keep`, modified files are committed for you; on `discard`/`crash`/`checks_failed`, the worktree is reverted. Pass `flag_runs` to mark earlier runs as suspect; flagged runs are excluded from baseline and best-metric math.
+- `log_experiment` — record the result. On `keep`, changes are committed only on a dedicated `autoresearch/*` branch; otherwise the tool warns and leaves files in the worktree. On `discard`/`crash`/`checks_failed`, the worktree is reverted. Pass `flag_runs` to mark earlier runs as suspect; flagged runs are excluded from baseline and best-metric math.
 - `update_notes` — replace the durable session playbook (`body`) or append to the ideas backlog (`append_idea`). The notes are injected into your system prompt every iteration.
 
 ### Operating protocol

package/src/autoresearch/tools/log-experiment.ts

@@ -62,7 +62,7 @@ export function createLogExperimentTool(
 		name: "log_experiment",
 		label: "Log Experiment",
 		description:
-			"Log the result of the latest run_experiment. Records the metric, optional ASI metadata, modified paths, and scope deviations. On `keep`, modified files are committed; on `discard`/`crash`/`checks_failed`, the worktree is reverted. Pass `flag_runs` to mark earlier runs as suspect; flagged runs are excluded from baseline and best-metric math.",
+			"Log the result of the latest run_experiment. Records the metric, optional ASI metadata, modified paths, and scope deviations. On `keep`, modified files are committed only on a dedicated `autoresearch/*` branch; otherwise the tool warns and leaves them in the worktree. On `discard`/`crash`/`checks_failed`, the worktree is reverted. Pass `flag_runs` to mark earlier runs as suspect; flagged runs are excluded from baseline and best-metric math.",
 		parameters: logExperimentSchema,
 		defaultInactive: true,
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/src/capability/mcp.ts

@@ -15,6 +15,8 @@ export interface MCPServer {
 	name: string;
 	/** Whether this server is enabled (default: true) */
 	enabled?: boolean;
+	/** Whether to connect automatically at session startup (default: true) */
+	autoload?: boolean;
 	/** Connection timeout in milliseconds */
 	timeout?: number;
 	/** Command to run (for stdio transport) */

package/src/capability/rule.ts

@@ -22,6 +22,11 @@ export interface RuleFrontmatter {
 	scope?: string | string[];
 	/** Per-rule TTSR interrupt mode override. */
 	interruptMode?: "never" | "prose-only" | "tool-only" | "always";
+	/** Per-rule TTSR repeat mode override. */
+	repeatMode?: "once" | "after-gap";
+	/** Per-rule TTSR repeat gap override. */
+	repeatGap?: number;
+
 	[key: string]: unknown;
 }
 
@@ -47,6 +52,10 @@ export interface Rule {
 	scope?: string[];
 	/** Per-rule TTSR interrupt mode override (falls back to global ttsr.interruptMode). */
 	interruptMode?: "never" | "prose-only" | "tool-only" | "always";
+	/** Per-rule TTSR repeat mode override (falls back to global ttsr.repeatMode). */
+	repeatMode?: "once" | "after-gap";
+	/** Per-rule TTSR repeat gap override (falls back to global ttsr.repeatGap). */
+	repeatGap?: number;
 	/** Source metadata */
 	_source: SourceMeta;
 }

package/src/cli/completion-cli.ts

@@ -0,0 +1,234 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ArgDescriptor, CommandCtor, CommandEntry, FlagDescriptor } from "@sayknow-cli/utils/cli";
+
+export type FigName = string | string[];
+
+export interface FigArg {
+	name: string;
+	description?: string;
+	isOptional?: boolean;
+	isVariadic?: boolean;
+	suggestions?: string[];
+}
+
+export interface FigOption {
+	name: FigName;
+	description?: string;
+	args?: FigArg;
+	isRepeatable?: boolean;
+}
+
+export interface FigSubcommand {
+	name: FigName;
+	description?: string;
+	options?: FigOption[];
+	args?: FigArg | FigArg[];
+}
+
+export interface FigSpec extends FigSubcommand {
+	name: string;
+	subcommands?: FigSubcommand[];
+}
+
+export type InshellisenseIndexStatus = "created" | "updated" | "already-compatible" | "overwritten";
+
+export interface InstallSkcInshellisenseSpecOptions {
+	dir?: string;
+	force?: boolean;
+}
+
+export interface InstallSkcInshellisenseSpecResult {
+	directory: string;
+	specPath: string;
+	indexPath: string;
+	indexStatus: InshellisenseIndexStatus;
+}
+
+const GENERATED_INDEX_MARKER = "// Generated by skc completion inshellisense";
+const BUILTIN_ROOT_OPTIONS: FigOption[] = [
+	{ name: ["-h", "--help"], description: "Show help" },
+	{ name: ["-v", "--version"], description: "Show version" },
+];
+const BUILTIN_COMMAND_OPTIONS: FigOption[] = [{ name: ["-h", "--help"], description: "Show help" }];
+
+export function defaultInshellisenseSpecDir(homeDir: string = os.homedir()): string {
+	return path.join(homeDir, ".fig", "autocomplete", "build");
+}
+
+function nameList(name: FigName): string[] {
+	return Array.isArray(name) ? name : [name];
+}
+
+function optionKey(option: FigOption): string {
+	return nameList(option.name).join("\u0000");
+}
+
+function combineOptions(primary: FigOption[], secondary: FigOption[]): FigOption[] {
+	const seen = new Set<string>();
+	const combined: FigOption[] = [];
+	for (const option of [...primary, ...secondary]) {
+		const key = optionKey(option);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		combined.push(option);
+	}
+	return combined;
+}
+
+function commandEntryName(entry: CommandEntry): FigName {
+	const names = [entry.name, ...(entry.aliases ?? [])];
+	return names.length === 1 ? names[0]! : names;
+}
+
+function flagName(name: string, descriptor: FlagDescriptor): FigName {
+	const longName = `--${name}`;
+	if (!descriptor.char) return longName;
+	return [`-${descriptor.char}`, longName];
+}
+
+function argSuggestions(options: readonly string[] | undefined): string[] | undefined {
+	return options && options.length > 0 ? [...options] : undefined;
+}
+
+function optionArgName(name: string, descriptor: FlagDescriptor): string {
+	if (descriptor.options && descriptor.options.length > 0) return name;
+	return descriptor.kind === "integer" ? "int" : "value";
+}
+
+function figOptionFromFlag(name: string, descriptor: FlagDescriptor): FigOption {
+	const option: FigOption = {
+		name: flagName(name, descriptor),
+	};
+	if (descriptor.description) option.description = descriptor.description;
+	if (descriptor.multiple) option.isRepeatable = true;
+	if (descriptor.kind !== "boolean") {
+		const arg: FigArg = { name: optionArgName(name, descriptor) };
+		const suggestions = argSuggestions(descriptor.options);
+		if (suggestions) arg.suggestions = suggestions;
+		option.args = arg;
+	}
+	return option;
+}
+
+function figOptionsFromFlags(flags: Record<string, FlagDescriptor> | undefined): FigOption[] {
+	if (!flags) return [];
+	return Object.entries(flags).map(([name, descriptor]) => figOptionFromFlag(name, descriptor));
+}
+
+function figArgFromDescriptor(name: string, descriptor: ArgDescriptor): FigArg {
+	const arg: FigArg = { name };
+	if (descriptor.description) arg.description = descriptor.description;
+	if (!descriptor.required) arg.isOptional = true;
+	if (descriptor.multiple) arg.isVariadic = true;
+	const suggestions = argSuggestions(descriptor.options);
+	if (suggestions) arg.suggestions = suggestions;
+	return arg;
+}
+
+function figArgsFromDescriptors(args: Record<string, ArgDescriptor> | undefined): FigArg | FigArg[] | undefined {
+	if (!args) return undefined;
+	const values = Object.entries(args).map(([name, descriptor]) => figArgFromDescriptor(name, descriptor));
+	if (values.length === 0) return undefined;
+	return values.length === 1 ? values[0] : values;
+}
+
+function commandToSubcommand(entry: CommandEntry, command: CommandCtor): FigSubcommand {
+	const subcommand: FigSubcommand = { name: commandEntryName(entry) };
+	if (command.description) subcommand.description = command.description;
+	const options = combineOptions(BUILTIN_COMMAND_OPTIONS, figOptionsFromFlags(command.flags));
+	if (options.length > 0) subcommand.options = options;
+	const args = figArgsFromDescriptors(command.args);
+	if (args) subcommand.args = args;
+	return subcommand;
+}
+
+export async function buildSkcFigSpec(entries: CommandEntry[], rootCommandOverride?: CommandCtor): Promise<FigSpec> {
+	const subcommands: FigSubcommand[] = [];
+	let rootCommand: CommandCtor | undefined = rootCommandOverride;
+
+	for (const entry of entries) {
+		if (entry.name === "launch" && rootCommandOverride) {
+			continue;
+		}
+		let command: CommandCtor;
+		try {
+			command = await entry.load();
+		} catch {
+			if (entry.name !== "launch") {
+				subcommands.push({ name: commandEntryName(entry) });
+			}
+			continue;
+		}
+		if (entry.name === "launch") {
+			rootCommand = command;
+			continue;
+		}
+		if (command.hidden) continue;
+		subcommands.push(commandToSubcommand(entry, command));
+	}
+
+	const spec: FigSpec = {
+		name: "skc",
+		description: rootCommand?.description ?? "Sayknow-CLI CLI",
+	};
+	const rootOptions = combineOptions(BUILTIN_ROOT_OPTIONS, figOptionsFromFlags(rootCommand?.flags));
+	if (rootOptions.length > 0) spec.options = rootOptions;
+	const rootArgs = figArgsFromDescriptors(rootCommand?.args);
+	if (rootArgs) spec.args = rootArgs;
+	if (subcommands.length > 0) spec.subcommands = subcommands;
+	return spec;
+}
+
+export function renderFigSpecModule(spec: FigSpec): string {
+	return `const completionSpec = ${JSON.stringify(spec, null, "\t")};\n\nexport default completionSpec;\n`;
+}
+
+export function renderInshellisenseIndexModule(): string {
+	return `${GENERATED_INDEX_MARKER}\n\nexport default ["skc"];\nexport const diffVersionedCompletions = [];\n`;
+}
+
+async function fileTextIfExists(filePath: string): Promise<string | undefined> {
+	try {
+		return await Bun.file(filePath).text();
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+function indexDeclaresSkc(content: string): boolean {
+	return /["']skc["']/.test(content);
+}
+
+async function resolveIndexStatus(indexPath: string, force: boolean | undefined): Promise<InshellisenseIndexStatus> {
+	const existing = await fileTextIfExists(indexPath);
+	if (existing === undefined) return "created";
+	if (existing.includes(GENERATED_INDEX_MARKER)) {
+		return existing === renderInshellisenseIndexModule() ? "already-compatible" : "updated";
+	}
+	if (indexDeclaresSkc(existing)) return "already-compatible";
+	if (force) return "overwritten";
+	throw new Error(
+		`inshellisense index already exists at ${indexPath} and does not list skc; rerun with --force to overwrite it or pass --dir to install into a SKC-only specs directory`,
+	);
+}
+
+export async function installSkcInshellisenseSpec(
+	spec: FigSpec,
+	options: InstallSkcInshellisenseSpecOptions = {},
+): Promise<InstallSkcInshellisenseSpecResult> {
+	const directory = path.resolve(options.dir ?? defaultInshellisenseSpecDir());
+	const specPath = path.join(directory, "skc.js");
+	const indexPath = path.join(directory, "index.js");
+	const indexStatus = await resolveIndexStatus(indexPath, options.force);
+
+	await fs.mkdir(directory, { recursive: true });
+	await Bun.write(specPath, renderFigSpecModule(spec));
+	if (indexStatus !== "already-compatible") {
+		await Bun.write(indexPath, renderInshellisenseIndexModule());
+	}
+
+	return { directory, specPath, indexPath, indexStatus };
+}

package/src/cli/config-cli.ts

@@ -33,6 +33,7 @@ export interface ConfigCommandArgs {
 	value?: string;
 	flags: {
 		json?: boolean;
+		showSecrets?: boolean;
 	};
 }
 // =============================================================================
@@ -47,6 +48,43 @@ type CliSettingDef = {
 };
 
 const ALL_SETTING_PATHS = Object.keys(SETTINGS_SCHEMA) as SettingPath[];
+const REDACTED_SECRET_VALUE = "<redacted>";
+const SECRET_SETTING_WORDS = new Set(["token", "secret", "password", "passwd", "pwd", "credential", "credentials"]);
+const SECRET_SETTING_COMPOUND_PREFIXES = [
+	"api",
+	"auth",
+	"access",
+	"refresh",
+	"bearer",
+	"session",
+	"client",
+	"broker",
+	"bot",
+	"basic",
+];
+const SECRET_SETTING_COMPOUND_SUFFIXES = ["token", "secret", "password", "credential"];
+
+function isSecretSettingSegment(segment: string): boolean {
+	const normalized = segment.toLowerCase();
+	if (SECRET_SETTING_WORDS.has(normalized)) return true;
+	if (/api[-_]?key/i.test(segment)) return true;
+	const words = normalized.split(/[-_]/).filter(Boolean);
+	if (words.some(word => SECRET_SETTING_WORDS.has(word))) return true;
+	return SECRET_SETTING_COMPOUND_PREFIXES.some(prefix =>
+		SECRET_SETTING_COMPOUND_SUFFIXES.some(suffix => normalized === `${prefix}${suffix}`),
+	);
+}
+
+function isSecretSettingPath(path: string): boolean {
+	return path.split(".").some(segment => isSecretSettingSegment(segment));
+}
+
+function redactConfigValue(path: string, value: unknown, showSecrets?: boolean): unknown {
+	if (showSecrets || value === undefined || value === null || !isSecretSettingPath(path)) {
+		return value;
+	}
+	return REDACTED_SECRET_VALUE;
+}
 
 /** Find setting definition by path */
 function findSettingDef(path: string): CliSettingDef | undefined {
@@ -105,6 +143,8 @@ export function parseConfigArgs(args: string[]): ConfigCommandArgs | undefined {
 		const arg = args[i];
 		if (arg === "--json") {
 			result.flags.json = true;
+		} else if (arg === "--show-secrets") {
+			result.flags.showSecrets = true;
 		} else if (!arg.startsWith("-")) {
 			positionalArgs.push(arg);
 		}
@@ -265,14 +305,15 @@ export async function runConfigCommand(cmd: ConfigCommandArgs): Promise<void> {
 	}
 }
 
-function handleList(flags: { json?: boolean }): void {
+function handleList(flags: { json?: boolean; showSecrets?: boolean }): void {
 	const defs = ALL_SETTING_PATHS.map(path => findSettingDef(path)).filter((def): def is CliSettingDef => !!def);
 
 	if (flags.json) {
 		const result: Record<string, { value: unknown; type: string; description: string }> = {};
 		for (const def of defs) {
+			const value = settings.get(def.path);
 			result[def.path] = {
-				value: settings.get(def.path),
+				value: redactConfigValue(def.path, value, flags.showSecrets),
 				type: def.type,
 				description: def.description,
 			};
@@ -301,7 +342,8 @@ function handleList(flags: { json?: boolean }): void {
 		console.log(chalk.bold.blue(`[${group}]`));
 		for (const def of groups[group]) {
 			const value = settings.get(def.path);
-			const valueStr = formatValue(value);
+			const displayValue = redactConfigValue(def.path, value, flags.showSecrets);
+			const valueStr = formatValue(displayValue);
 			const typeStr = getTypeDisplay(def);
 			console.log(`  ${chalk.white(def.path)} = ${valueStr} ${chalk.dim(typeStr)}`);
 		}
@@ -309,7 +351,7 @@ function handleList(flags: { json?: boolean }): void {
 	}
 }
 
-function handleGet(key: string | undefined, flags: { json?: boolean }): void {
+function handleGet(key: string | undefined, flags: { json?: boolean; showSecrets?: boolean }): void {
 	if (!key) {
 		console.error(chalk.red(`Usage: ${APP_NAME} config get <key>`));
 		console.error(chalk.dim(`\nRun '${APP_NAME} config list' to see available keys`));
@@ -324,16 +366,23 @@ function handleGet(key: string | undefined, flags: { json?: boolean }): void {
 	}
 
 	const value = settings.get(def.path);
+	const displayValue = redactConfigValue(def.path, value, flags.showSecrets);
 
 	if (flags.json) {
-		console.log(JSON.stringify({ key: def.path, value, type: def.type, description: def.description }, null, 2));
+		console.log(
+			JSON.stringify({ key: def.path, value: displayValue, type: def.type, description: def.description }, null, 2),
+		);
 		return;
 	}
 
-	console.log(formatValue(value));
+	console.log(formatValue(displayValue));
 }
 
-async function handleSet(key: string | undefined, value: string | undefined, flags: { json?: boolean }): Promise<void> {
+async function handleSet(
+	key: string | undefined,
+	value: string | undefined,
+	flags: { json?: boolean; showSecrets?: boolean },
+): Promise<void> {
 	if (!key || value === undefined) {
 		console.error(chalk.red(`Usage: ${APP_NAME} config set <key> <value>`));
 		console.error(chalk.dim(`\nRun '${APP_NAME} config list' to see available keys`));
@@ -355,11 +404,12 @@ async function handleSet(key: string | undefined, value: string | undefined, fla
 	}
 
 	const newValue = settings.get(def.path);
+	const displayValue = redactConfigValue(def.path, newValue, flags.showSecrets);
 
 	if (flags.json) {
-		console.log(JSON.stringify({ key: def.path, value: newValue }));
+		console.log(JSON.stringify({ key: def.path, value: displayValue }));
 	} else {
-		console.log(chalk.green(`${theme.status.success} Set ${def.path} = ${formatValue(newValue)}`));
+		console.log(chalk.green(`${theme.status.success} Set ${def.path} = ${formatValue(displayValue)}`));
 	}
 }
 
@@ -409,6 +459,7 @@ ${chalk.bold("Commands:")}
 
 ${chalk.bold("Options:")}
   --json             Output as JSON
+  --show-secrets     Show secret-like setting values without redaction (unsafe)
 
 ${chalk.bold("Examples:")}
   ${APP_NAME} config list
@@ -418,6 +469,7 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} config set defaultThinkingLevel medium
   ${APP_NAME} config reset steeringMode
   ${APP_NAME} config list --json
+  ${APP_NAME} config get auth.broker.token --show-secrets
   ${APP_NAME} config init-xdg
 
 ${chalk.bold("Boolean Values:")}

package/src/cli/fast-help.ts

@@ -15,6 +15,7 @@ export function getExtraHelpText(): string {
   ${APP_NAME} deep-interview       - Run requirements interview workflow
   ${APP_NAME} skills               - List/read embedded workflow skills
   ${APP_NAME} config               - List, get, and set configuration values
+  ${APP_NAME} stats                - View AI usage statistics (tokens, cost, requests)
   ${APP_NAME} notify               - Send or test notifications
   ${APP_NAME} daemon               - Manage background daemon helpers
   ${APP_NAME} mcp                  - Manage MCP server registrations