@f5xc-salesdemos/xcsh 2.2.0 → 14.0.2

package/src/web/search/types.ts

@@ -0,0 +1,434 @@
+/**
+ * Web Search Types
+ *
+ * Unified types for web search responses across supported providers.
+ */
+
+/** Supported web search providers */
+export type SearchProviderId =
+	| "exa"
+	| "brave"
+	| "jina"
+	| "kimi"
+	| "zai"
+	| "anthropic"
+	| "perplexity"
+	| "gemini"
+	| "codex"
+	| "tavily"
+	| "parallel"
+	| "kagi"
+	| "synthetic";
+
+export function isSearchProviderId(value: string): value is SearchProviderId {
+	return [
+		"exa",
+		"brave",
+		"jina",
+		"kimi",
+		"zai",
+		"anthropic",
+		"perplexity",
+		"gemini",
+		"codex",
+		"tavily",
+		"parallel",
+		"kagi",
+		"synthetic",
+	].includes(value);
+}
+
+export function isSearchProviderPreference(value: string): value is SearchProviderId | "auto" {
+	return value === "auto" || isSearchProviderId(value);
+}
+
+/** Source returned by search (all providers) */
+export interface SearchSource {
+	title: string;
+	url: string;
+	snippet?: string;
+	/** ISO date string or relative ("2d ago") */
+	publishedDate?: string;
+	/** Age in seconds for consistent formatting */
+	ageSeconds?: number;
+	author?: string;
+}
+
+/** Citation with text reference (anthropic, perplexity) */
+export interface SearchCitation {
+	url: string;
+	title: string;
+	citedText?: string;
+}
+
+/** Usage metrics */
+export interface SearchUsage {
+	inputTokens?: number;
+	outputTokens?: number;
+	/** Anthropic: number of web search requests made */
+	searchRequests?: number;
+	/** Perplexity: combined token count */
+	totalTokens?: number;
+}
+
+/** Unified response across providers */
+export interface SearchResponse {
+	provider: SearchProviderId | "none";
+	/** Synthesized answer text (anthropic, perplexity) */
+	answer?: string;
+	/** Search result sources */
+	sources: SearchSource[];
+	/** Text citations with context */
+	citations?: SearchCitation[];
+	/** Intermediate search queries (anthropic) */
+	searchQueries?: string[];
+	/** Follow-up question suggestions (provider-dependent) */
+	relatedQuestions?: string[];
+	/** Token usage metrics */
+	usage?: SearchUsage;
+	/** Model used */
+	model?: string;
+	/** Request ID for debugging */
+	requestId?: string;
+	/** Authentication mode used by the provider (e.g. oauth, api-key) */
+	authMode?: string;
+}
+
+/** Provider-specific error with optional HTTP status */
+export class SearchProviderError extends Error {
+	constructor(
+		public readonly provider: SearchProviderId,
+		message: string,
+		public readonly status?: number,
+	) {
+		super(message);
+		this.name = "SearchProviderError";
+	}
+}
+
+/** Anthropic API response types */
+export interface AnthropicSearchResult {
+	type: "web_search_result";
+	title: string;
+	url: string;
+	encrypted_content: string;
+	page_age: string | null;
+}
+
+export interface AnthropicCitation {
+	type: "web_search_result_location";
+	url: string;
+	title: string;
+	cited_text: string;
+	encrypted_index: string;
+}
+
+export interface AnthropicContentBlock {
+	type: string;
+	/** Text content (for type="text") */
+	text?: string;
+	/** Citations in text block */
+	citations?: AnthropicCitation[];
+	/** Tool name (for type="server_tool_use") */
+	name?: string;
+	/** Tool input (for type="server_tool_use") */
+	input?: { query: string };
+	/** Search results (for type="web_search_tool_result") */
+	content?: AnthropicSearchResult[];
+}
+
+export interface AnthropicApiResponse {
+	id: string;
+	model: string;
+	content: AnthropicContentBlock[];
+	usage: {
+		input_tokens: number;
+		output_tokens: number;
+		cache_read_input_tokens?: number;
+		cache_creation_input_tokens?: number;
+		server_tool_use?: { web_search_requests: number };
+	};
+}
+
+/** Perplexity API types */
+export type PerplexityChatMessageRole = "system" | "user" | "assistant" | "tool";
+
+export interface PerplexityUrl {
+	url: string;
+}
+
+export interface PerplexityVideoUrl {
+	url: string;
+	frame_interval?: string | number;
+}
+
+export interface PerplexityContentTextChunk {
+	type: "text";
+	text: string;
+}
+
+export interface PerplexityContentImageChunk {
+	type: "image_url";
+	image_url: PerplexityUrl | string;
+}
+
+export interface PerplexityContentFileChunk {
+	type: "file_url";
+	file_url: PerplexityUrl | string;
+	file_name?: string | null;
+}
+
+export interface PerplexityContentPdfChunk {
+	type: "pdf_url";
+	pdf_url: PerplexityUrl | string;
+}
+
+export interface PerplexityContentVideoChunk {
+	type: "video_url";
+	video_url: PerplexityVideoUrl | string;
+}
+
+export type PerplexityContentChunk =
+	| PerplexityContentTextChunk
+	| PerplexityContentImageChunk
+	| PerplexityContentFileChunk
+	| PerplexityContentPdfChunk
+	| PerplexityContentVideoChunk;
+
+export interface PerplexitySearchStepDetails {
+	search_results: PerplexitySearchResult[];
+	search_keywords: string[];
+}
+
+export interface PerplexityFetchUrlContentStepDetails {
+	contents: PerplexitySearchResult[];
+}
+
+export interface PerplexityExecutePythonStepDetails {
+	code: string;
+	result: string;
+}
+
+export interface PerplexityReasoningStepInput {
+	thought: string;
+	type?: string | null;
+	web_search?: PerplexitySearchStepDetails | null;
+	fetch_url_content?: PerplexityFetchUrlContentStepDetails | null;
+	execute_python?: PerplexityExecutePythonStepDetails | null;
+}
+
+export interface PerplexityReasoningStepOutput {
+	thought: string;
+	type?: string | null;
+	web_search?: PerplexitySearchStepDetails | null;
+	fetch_url_content?: PerplexityFetchUrlContentStepDetails | null;
+	execute_python?: PerplexityExecutePythonStepDetails | null;
+}
+
+export interface PerplexityToolCallFunction {
+	name?: string | null;
+	arguments?: string | null;
+}
+
+export interface PerplexityToolCall {
+	id?: string | null;
+	type?: "function" | null;
+	function?: PerplexityToolCallFunction | null;
+}
+
+export interface PerplexityMessageInput {
+	role: PerplexityChatMessageRole;
+	content: string | PerplexityContentChunk[] | null;
+	reasoning_steps?: PerplexityReasoningStepInput[] | null;
+	tool_calls?: PerplexityToolCall[] | null;
+	tool_call_id?: string | null;
+}
+
+export interface PerplexityMessageOutput {
+	role: PerplexityChatMessageRole;
+	content: string | PerplexityContentChunk[] | null;
+	reasoning_steps?: PerplexityReasoningStepOutput[] | null;
+	tool_calls?: PerplexityToolCall[] | null;
+	tool_call_id?: string | null;
+}
+
+export type PerplexityMessage = PerplexityMessageInput;
+
+export interface PerplexityResponseFormatText {
+	type: "text";
+}
+
+export interface PerplexityJSONSchema {
+	schema: Record<string, unknown>;
+	name?: string | null;
+	description?: string | null;
+	strict?: boolean | null;
+}
+
+export interface PerplexityResponseFormatJSONSchema {
+	type: "json_schema";
+	json_schema: PerplexityJSONSchema;
+}
+
+export interface PerplexityRegexSchema {
+	regex: string;
+	name?: string | null;
+	description?: string | null;
+	strict?: boolean | null;
+}
+
+export interface PerplexityResponseFormatRegex {
+	type: "regex";
+	regex: PerplexityRegexSchema;
+}
+
+export type PerplexityResponseFormat =
+	| PerplexityResponseFormatText
+	| PerplexityResponseFormatJSONSchema
+	| PerplexityResponseFormatRegex;
+
+export interface PerplexityParameterSpec {
+	type: string;
+	properties: Record<string, unknown>;
+	required?: string[] | null;
+	additional_properties?: boolean | null;
+}
+
+export interface PerplexityFunctionSpec {
+	name: string;
+	description: string;
+	parameters: PerplexityParameterSpec;
+	strict?: boolean | null;
+}
+
+export interface PerplexityToolSpec {
+	type: "function";
+	function: PerplexityFunctionSpec;
+}
+
+export interface PerplexityUserLocation {
+	latitude?: number | null;
+	longitude?: number | null;
+	country?: string | null;
+	city?: string | null;
+	region?: string | null;
+}
+
+export interface PerplexitySearchOptions {
+	search_context_size?: "low" | "medium" | "high";
+	search_type?: "fast" | "pro" | "auto" | null;
+	user_location?: PerplexityUserLocation | null;
+	image_results_enhanced_relevance?: boolean;
+}
+
+export interface PerplexityRequest {
+	max_tokens?: number | null;
+	temperature?: number | null;
+	n?: number | null;
+	model: string;
+	stream?: boolean | null;
+	stop?: string | string[] | null;
+	cum_logprobs?: boolean | null;
+	logprobs?: boolean | null;
+	top_logprobs?: number | null;
+	best_of?: number | null;
+	response_metadata?: Record<string, unknown> | null;
+	response_format?: PerplexityResponseFormat | null;
+	diverse_first_token?: boolean | null;
+	_inputs?: number[] | null;
+	_prompt_token_length?: number | null;
+	messages: PerplexityMessageInput[];
+	tools?: PerplexityToolSpec[] | null;
+	tool_choice?: "none" | "auto" | "required" | null;
+	parallel_tool_calls?: boolean | null;
+	web_search_options?: PerplexitySearchOptions;
+	search_mode?: "web" | "academic" | "sec" | null;
+	return_images?: boolean | null;
+	return_related_questions?: boolean | null;
+	num_search_results?: number;
+	num_images?: number;
+	enable_search_classifier?: boolean | null;
+	disable_search?: boolean | null;
+	search_domain_filter?: string[] | null;
+	search_language_filter?: string[] | null;
+	search_tenant?: string | null;
+	ranking_model?: string | null;
+	latitude?: number | null;
+	longitude?: number | null;
+	country?: string | null;
+	search_recency_filter?: "hour" | "day" | "week" | "month" | "year" | null;
+	search_after_date_filter?: string | null;
+	search_before_date_filter?: string | null;
+	last_updated_before_filter?: string | null;
+	last_updated_after_filter?: string | null;
+	image_format_filter?: string[] | null;
+	image_domain_filter?: string[] | null;
+	safe_search?: boolean | null;
+	file_workspace_id?: string | null;
+	updated_before_timestamp?: number | null;
+	updated_after_timestamp?: number | null;
+	search_internal_properties?: Record<string, unknown> | null;
+	use_threads?: boolean | null;
+	thread_id?: string | null;
+	stream_mode?: "full" | "concise";
+	_debug_pro_search?: boolean;
+	has_image_url?: boolean;
+	reasoning_effort?: "minimal" | "low" | "medium" | "high" | null;
+	language_preference?: string | null;
+	user_original_query?: string | null;
+	_force_new_agent?: boolean | null;
+}
+
+export interface PerplexitySearchResult {
+	title: string;
+	url: string;
+	date?: string | null;
+	last_updated?: string | null;
+	snippet?: string;
+	source?: "web" | "attachment";
+}
+
+export interface PerplexityCost {
+	input_tokens_cost: number;
+	output_tokens_cost: number;
+	reasoning_tokens_cost?: number | null;
+	request_cost?: number | null;
+	citation_tokens_cost?: number | null;
+	search_queries_cost?: number | null;
+	total_cost: number;
+}
+
+export interface PerplexityUsageInfo {
+	prompt_tokens: number;
+	completion_tokens: number;
+	total_tokens: number;
+	search_context_size?: string | null;
+	citation_tokens?: number | null;
+	num_search_queries?: number | null;
+	reasoning_tokens?: number | null;
+	cost: PerplexityCost;
+}
+
+export type PerplexityCompletionResponseType = "message" | "info" | "end_of_stream";
+
+export type PerplexityCompletionResponseStatus = "PENDING" | "COMPLETED";
+
+export interface PerplexityChoice {
+	index: number;
+	finish_reason?: "stop" | "length" | null;
+	message: PerplexityMessageOutput;
+	delta: PerplexityMessageOutput;
+}
+
+export interface PerplexityResponse {
+	id: string;
+	model: string;
+	created: number;
+	usage?: PerplexityUsageInfo | null;
+	object?: string;
+	choices: PerplexityChoice[];
+	citations?: string[] | null;
+	search_results?: PerplexitySearchResult[] | null;
+	type?: PerplexityCompletionResponseType | null;
+	status?: PerplexityCompletionResponseStatus | null;
+}

package/src/web/search/utils.ts

@@ -0,0 +1,17 @@
+/** Calculate age in seconds from an ISO date string. Returns undefined on invalid input. */
+export function dateToAgeSeconds(dateStr: string | null | undefined): number | undefined {
+	if (!dateStr) return undefined;
+	try {
+		const date = new Date(dateStr);
+		if (Number.isNaN(date.getTime())) return undefined;
+		return Math.floor((Date.now() - date.getTime()) / 1000);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Clamp a result count to [1, maxVal], returning defaultVal when value is absent or NaN. */
+export function clampNumResults(value: number | undefined, defaultVal: number, maxVal: number): number {
+	if (!value || Number.isNaN(value)) return defaultVal;
+	return Math.min(maxVal, Math.max(1, value));
+}

package/dist/bun/cli.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/bun/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/bun/cli.ts"],"names":[],"mappings":"","sourcesContent":["#!/usr/bin/env node\nprocess.title = \"xcsh\";\nprocess.emitWarning = (() => {}) as typeof process.emitWarning;\n\nawait import(\"./register-bedrock.js\");\nawait import(\"../cli.js\");\n"]}

package/dist/bun/cli.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-process.title = "xcsh";
-process.emitWarning = (() => { });
-await import("./register-bedrock.js");
-await import("../cli.js");
-export {};
-//# sourceMappingURL=cli.js.map

package/dist/bun/cli.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/bun/cli.ts"],"names":[],"mappings":";AACA,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC;AACvB,OAAO,CAAC,WAAW,GAAG,CAAC,GAAG,EAAE,CAAC,EAAC,CAAC,CAA+B,CAAC;AAE/D,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;AACtC,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nprocess.title = \"xcsh\";\nprocess.emitWarning = (() => {}) as typeof process.emitWarning;\n\nawait import(\"./register-bedrock.js\");\nawait import(\"../cli.js\");\n"]}

package/dist/bun/register-bedrock.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=register-bedrock.d.ts.map

package/dist/bun/register-bedrock.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"register-bedrock.d.ts","sourceRoot":"","sources":["../../src/bun/register-bedrock.ts"],"names":[],"mappings":"","sourcesContent":["import { setBedrockProviderModule } from \"@f5xc-salesdemos/xcsh-ai\";\nimport { bedrockProviderModule } from \"@f5xc-salesdemos/xcsh-ai/bedrock-provider\";\n\nsetBedrockProviderModule(bedrockProviderModule);\n"]}

package/dist/bun/register-bedrock.js

@@ -1,4 +0,0 @@
-import { setBedrockProviderModule } from "@f5xc-salesdemos/xcsh-ai";
-import { bedrockProviderModule } from "@f5xc-salesdemos/xcsh-ai/bedrock-provider";
-setBedrockProviderModule(bedrockProviderModule);
-//# sourceMappingURL=register-bedrock.js.map

package/dist/bun/register-bedrock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"register-bedrock.js","sourceRoot":"","sources":["../../src/bun/register-bedrock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAElF,wBAAwB,CAAC,qBAAqB,CAAC,CAAC","sourcesContent":["import { setBedrockProviderModule } from \"@f5xc-salesdemos/xcsh-ai\";\nimport { bedrockProviderModule } from \"@f5xc-salesdemos/xcsh-ai/bedrock-provider\";\n\nsetBedrockProviderModule(bedrockProviderModule);\n"]}

package/dist/cli/args.d.ts

@@ -1,52 +0,0 @@
-/**
- * CLI argument parsing and help display
- */
-import type { ThinkingLevel } from "@f5xc-salesdemos/xcsh-agent-core";
-import type { ExtensionFlag } from "../core/extensions/types.js";
-import { type ToolName } from "../core/tools/index.js";
-export type Mode = "text" | "json" | "rpc";
-export interface Args {
-    provider?: string;
-    model?: string;
-    apiKey?: string;
-    systemPrompt?: string;
-    appendSystemPrompt?: string;
-    thinking?: ThinkingLevel;
-    continue?: boolean;
-    resume?: boolean;
-    help?: boolean;
-    version?: boolean;
-    mode?: Mode;
-    noSession?: boolean;
-    session?: string;
-    fork?: string;
-    sessionDir?: string;
-    models?: string[];
-    tools?: ToolName[];
-    noTools?: boolean;
-    extensions?: string[];
-    noExtensions?: boolean;
-    print?: boolean;
-    export?: string;
-    noSkills?: boolean;
-    skills?: string[];
-    promptTemplates?: string[];
-    noPromptTemplates?: boolean;
-    themes?: string[];
-    noThemes?: boolean;
-    listModels?: string | true;
-    offline?: boolean;
-    verbose?: boolean;
-    messages: string[];
-    fileArgs: string[];
-    /** Unknown flags (potentially extension flags) - map of flag name to value */
-    unknownFlags: Map<string, boolean | string>;
-    diagnostics: Array<{
-        type: "warning" | "error";
-        message: string;
-    }>;
-}
-export declare function isValidThinkingLevel(level: string): level is ThinkingLevel;
-export declare function parseArgs(args: string[]): Args;
-export declare function printHelp(extensionFlags?: ExtensionFlag[]): void;
-//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAGtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEjE,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAE3C,MAAM,WAAW,IAAI;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8EAA8E;IAC9E,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;IAC5C,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnE;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,aAAa,CAE1E;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAiI9C;AAED,wBAAgB,SAAS,CAAC,cAAc,CAAC,EAAE,aAAa,EAAE,GAAG,IAAI,CAqJhE","sourcesContent":["/**\n * CLI argument parsing and help display\n */\n\nimport type { ThinkingLevel } from \"@f5xc-salesdemos/xcsh-agent-core\";\nimport chalk from \"chalk\";\nimport { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from \"../config.js\";\nimport type { ExtensionFlag } from \"../core/extensions/types.js\";\nimport { allTools, type ToolName } from \"../core/tools/index.js\";\n\nexport type Mode = \"text\" | \"json\" | \"rpc\";\n\nexport interface Args {\n\tprovider?: string;\n\tmodel?: string;\n\tapiKey?: string;\n\tsystemPrompt?: string;\n\tappendSystemPrompt?: string;\n\tthinking?: ThinkingLevel;\n\tcontinue?: boolean;\n\tresume?: boolean;\n\thelp?: boolean;\n\tversion?: boolean;\n\tmode?: Mode;\n\tnoSession?: boolean;\n\tsession?: string;\n\tfork?: string;\n\tsessionDir?: string;\n\tmodels?: string[];\n\ttools?: ToolName[];\n\tnoTools?: boolean;\n\textensions?: string[];\n\tnoExtensions?: boolean;\n\tprint?: boolean;\n\texport?: string;\n\tnoSkills?: boolean;\n\tskills?: string[];\n\tpromptTemplates?: string[];\n\tnoPromptTemplates?: boolean;\n\tthemes?: string[];\n\tnoThemes?: boolean;\n\tlistModels?: string | true;\n\toffline?: boolean;\n\tverbose?: boolean;\n\tmessages: string[];\n\tfileArgs: string[];\n\t/** Unknown flags (potentially extension flags) - map of flag name to value */\n\tunknownFlags: Map<string, boolean | string>;\n\tdiagnostics: Array<{ type: \"warning\" | \"error\"; message: string }>;\n}\n\nconst VALID_THINKING_LEVELS = [\"off\", \"minimal\", \"low\", \"medium\", \"high\", \"xhigh\"] as const;\n\nexport function isValidThinkingLevel(level: string): level is ThinkingLevel {\n\treturn VALID_THINKING_LEVELS.includes(level as ThinkingLevel);\n}\n\nexport function parseArgs(args: string[]): Args {\n\tconst result: Args = {\n\t\tmessages: [],\n\t\tfileArgs: [],\n\t\tunknownFlags: new Map(),\n\t\tdiagnostics: [],\n\t};\n\n\tfor (let i = 0; i < args.length; i++) {\n\t\tconst arg = args[i];\n\n\t\tif (arg === \"--help\" || arg === \"-h\") {\n\t\t\tresult.help = true;\n\t\t} else if (arg === \"--version\" || arg === \"-v\") {\n\t\t\tresult.version = true;\n\t\t} else if (arg === \"--mode\" && i + 1 < args.length) {\n\t\t\tconst mode = args[++i];\n\t\t\tif (mode === \"text\" || mode === \"json\" || mode === \"rpc\") {\n\t\t\t\tresult.mode = mode;\n\t\t\t}\n\t\t} else if (arg === \"--continue\" || arg === \"-c\") {\n\t\t\tresult.continue = true;\n\t\t} else if (arg === \"--resume\" || arg === \"-r\") {\n\t\t\tresult.resume = true;\n\t\t} else if (arg === \"--provider\" && i + 1 < args.length) {\n\t\t\tresult.provider = args[++i];\n\t\t} else if (arg === \"--model\" && i + 1 < args.length) {\n\t\t\tresult.model = args[++i];\n\t\t} else if (arg === \"--api-key\" && i + 1 < args.length) {\n\t\t\tresult.apiKey = args[++i];\n\t\t} else if (arg === \"--system-prompt\" && i + 1 < args.length) {\n\t\t\tresult.systemPrompt = args[++i];\n\t\t} else if (arg === \"--append-system-prompt\" && i + 1 < args.length) {\n\t\t\tresult.appendSystemPrompt = args[++i];\n\t\t} else if (arg === \"--no-session\") {\n\t\t\tresult.noSession = true;\n\t\t} else if (arg === \"--session\" && i + 1 < args.length) {\n\t\t\tresult.session = args[++i];\n\t\t} else if (arg === \"--fork\" && i + 1 < args.length) {\n\t\t\tresult.fork = args[++i];\n\t\t} else if (arg === \"--session-dir\" && i + 1 < args.length) {\n\t\t\tresult.sessionDir = args[++i];\n\t\t} else if (arg === \"--models\" && i + 1 < args.length) {\n\t\t\tresult.models = args[++i].split(\",\").map((s) => s.trim());\n\t\t} else if (arg === \"--no-tools\") {\n\t\t\tresult.noTools = true;\n\t\t} else if (arg === \"--tools\" && i + 1 < args.length) {\n\t\t\tconst toolNames = args[++i].split(\",\").map((s) => s.trim());\n\t\t\tconst validTools: ToolName[] = [];\n\t\t\tfor (const name of toolNames) {\n\t\t\t\tif (name in allTools) {\n\t\t\t\t\tvalidTools.push(name as ToolName);\n\t\t\t\t} else {\n\t\t\t\t\tresult.diagnostics.push({\n\t\t\t\t\t\ttype: \"warning\",\n\t\t\t\t\t\tmessage: `Unknown tool \"${name}\". Valid tools: ${Object.keys(allTools).join(\", \")}`,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t\tresult.tools = validTools;\n\t\t} else if (arg === \"--thinking\" && i + 1 < args.length) {\n\t\t\tconst level = args[++i];\n\t\t\tif (isValidThinkingLevel(level)) {\n\t\t\t\tresult.thinking = level;\n\t\t\t} else {\n\t\t\t\tresult.diagnostics.push({\n\t\t\t\t\ttype: \"warning\",\n\t\t\t\t\tmessage: `Invalid thinking level \"${level}\". Valid values: ${VALID_THINKING_LEVELS.join(\", \")}`,\n\t\t\t\t});\n\t\t\t}\n\t\t} else if (arg === \"--print\" || arg === \"-p\") {\n\t\t\tresult.print = true;\n\t\t} else if (arg === \"--export\" && i + 1 < args.length) {\n\t\t\tresult.export = args[++i];\n\t\t} else if ((arg === \"--extension\" || arg === \"-e\") && i + 1 < args.length) {\n\t\t\tresult.extensions = result.extensions ?? [];\n\t\t\tresult.extensions.push(args[++i]);\n\t\t} else if (arg === \"--no-extensions\" || arg === \"-ne\") {\n\t\t\tresult.noExtensions = true;\n\t\t} else if (arg === \"--skill\" && i + 1 < args.length) {\n\t\t\tresult.skills = result.skills ?? [];\n\t\t\tresult.skills.push(args[++i]);\n\t\t} else if (arg === \"--prompt-template\" && i + 1 < args.length) {\n\t\t\tresult.promptTemplates = result.promptTemplates ?? [];\n\t\t\tresult.promptTemplates.push(args[++i]);\n\t\t} else if (arg === \"--theme\" && i + 1 < args.length) {\n\t\t\tresult.themes = result.themes ?? [];\n\t\t\tresult.themes.push(args[++i]);\n\t\t} else if (arg === \"--no-skills\" || arg === \"-ns\") {\n\t\t\tresult.noSkills = true;\n\t\t} else if (arg === \"--no-prompt-templates\" || arg === \"-np\") {\n\t\t\tresult.noPromptTemplates = true;\n\t\t} else if (arg === \"--no-themes\") {\n\t\t\tresult.noThemes = true;\n\t\t} else if (arg === \"--list-models\") {\n\t\t\t// Check if next arg is a search pattern (not a flag or file arg)\n\t\t\tif (i + 1 < args.length && !args[i + 1].startsWith(\"-\") && !args[i + 1].startsWith(\"@\")) {\n\t\t\t\tresult.listModels = args[++i];\n\t\t\t} else {\n\t\t\t\tresult.listModels = true;\n\t\t\t}\n\t\t} else if (arg === \"--verbose\") {\n\t\t\tresult.verbose = true;\n\t\t} else if (arg === \"--offline\") {\n\t\t\tresult.offline = true;\n\t\t} else if (arg.startsWith(\"@\")) {\n\t\t\tresult.fileArgs.push(arg.slice(1)); // Remove @ prefix\n\t\t} else if (arg.startsWith(\"--\")) {\n\t\t\tconst eqIndex = arg.indexOf(\"=\");\n\t\t\tif (eqIndex !== -1) {\n\t\t\t\tresult.unknownFlags.set(arg.slice(2, eqIndex), arg.slice(eqIndex + 1));\n\t\t\t} else {\n\t\t\t\tconst flagName = arg.slice(2);\n\t\t\t\tconst next = args[i + 1];\n\t\t\t\tif (next !== undefined && !next.startsWith(\"-\") && !next.startsWith(\"@\")) {\n\t\t\t\t\tresult.unknownFlags.set(flagName, next);\n\t\t\t\t\ti++;\n\t\t\t\t} else {\n\t\t\t\t\tresult.unknownFlags.set(flagName, true);\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (arg.startsWith(\"-\") && !arg.startsWith(\"--\")) {\n\t\t\tresult.diagnostics.push({ type: \"error\", message: `Unknown option: ${arg}` });\n\t\t} else if (!arg.startsWith(\"-\")) {\n\t\t\tresult.messages.push(arg);\n\t\t}\n\t}\n\n\treturn result;\n}\n\nexport function printHelp(extensionFlags?: ExtensionFlag[]): void {\n\tconst extensionFlagsText =\n\t\textensionFlags && extensionFlags.length > 0\n\t\t\t? `\\n${chalk.bold(\"Extension CLI Flags:\")}\\n${extensionFlags\n\t\t\t\t\t.map((flag) => {\n\t\t\t\t\t\tconst value = flag.type === \"string\" ? \" <value>\" : \"\";\n\t\t\t\t\t\tconst description = flag.description ?? `Registered by ${flag.extensionPath}`;\n\t\t\t\t\t\treturn `  --${flag.name}${value}`.padEnd(30) + description;\n\t\t\t\t\t})\n\t\t\t\t\t.join(\"\\n\")}\\n`\n\t\t\t: \"\";\n\tconsole.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools\n\n${chalk.bold(\"Usage:\")}\n  ${APP_NAME} [options] [@files...] [messages...]\n\n${chalk.bold(\"Commands:\")}\n  ${APP_NAME} install <source> [-l]     Install extension source and add to settings\n  ${APP_NAME} remove <source> [-l]      Remove extension source from settings\n  ${APP_NAME} uninstall <source> [-l]   Alias for remove\n  ${APP_NAME} update [source]           Update installed extensions (skips pinned sources)\n  ${APP_NAME} list                      List installed extensions from settings\n  ${APP_NAME} config                    Open TUI to enable/disable package resources\n  ${APP_NAME} <command> --help          Show help for install/remove/uninstall/update/list\n\n${chalk.bold(\"Options:\")}\n  --provider <name>              Provider name (default: google)\n  --model <pattern>              Model pattern or ID (supports \"provider/id\" and optional \":<thinking>\")\n  --api-key <key>                API key (defaults to env vars)\n  --system-prompt <text>         System prompt (default: coding assistant prompt)\n  --append-system-prompt <text>  Append text or file contents to the system prompt\n  --mode <mode>                  Output mode: text (default), json, or rpc\n  --print, -p                    Non-interactive mode: process prompt and exit\n  --continue, -c                 Continue previous session\n  --resume, -r                   Select a session to resume\n  --session <path>               Use specific session file\n  --fork <path>                  Fork specific session file or partial UUID into a new session\n  --session-dir <dir>            Directory for session storage and lookup\n  --no-session                   Don't save session (ephemeral)\n  --models <patterns>            Comma-separated model patterns for Ctrl+P cycling\n                                 Supports globs (anthropic/*, *sonnet*) and fuzzy matching\n  --no-tools                     Disable all built-in tools\n  --tools <tools>                Comma-separated list of tools to enable (default: read,bash,edit,write)\n                                 Available: read, bash, edit, write, grep, find, ls\n  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh\n  --extension, -e <path>         Load an extension file (can be used multiple times)\n  --no-extensions, -ne           Disable extension discovery (explicit -e paths still work)\n  --skill <path>                 Load a skill file or directory (can be used multiple times)\n  --no-skills, -ns               Disable skills discovery and loading\n  --prompt-template <path>       Load a prompt template file or directory (can be used multiple times)\n  --no-prompt-templates, -np     Disable prompt template discovery and loading\n  --theme <path>                 Load a theme file or directory (can be used multiple times)\n  --no-themes                    Disable theme discovery and loading\n  --export <file>                Export session file to HTML and exit\n  --list-models [search]         List available models (with optional fuzzy search)\n  --verbose                      Force verbose startup (overrides quietStartup setting)\n  --offline                      Disable startup network operations (same as XCSH_OFFLINE=1)\n  --help, -h                     Show this help\n  --version, -v                  Show version number\n\nExtensions can register additional flags (e.g., --plan from plan-mode extension).${extensionFlagsText}\n\n${chalk.bold(\"Examples:\")}\n  # Interactive mode\n  ${APP_NAME}\n\n  # Interactive mode with initial prompt\n  ${APP_NAME} \"List all .ts files in src/\"\n\n  # Include files in initial message\n  ${APP_NAME} @prompt.md @image.png \"What color is the sky?\"\n\n  # Non-interactive mode (process and exit)\n  ${APP_NAME} -p \"List all .ts files in src/\"\n\n  # Multiple messages (interactive)\n  ${APP_NAME} \"Read package.json\" \"What dependencies do we have?\"\n\n  # Continue previous session\n  ${APP_NAME} --continue \"What did we discuss?\"\n\n  # Use different model\n  ${APP_NAME} --provider openai --model gpt-4o-mini \"Help me refactor this code\"\n\n  # Use model with provider prefix (no --provider needed)\n  ${APP_NAME} --model openai/gpt-4o \"Help me refactor this code\"\n\n  # Use model with thinking level shorthand\n  ${APP_NAME} --model sonnet:high \"Solve this complex problem\"\n\n  # Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o\n\n  # Limit to a specific provider with glob pattern\n  ${APP_NAME} --models \"github-copilot/*\"\n\n  # Cycle models with fixed thinking levels\n  ${APP_NAME} --models sonnet:high,haiku:low\n\n  # Start with a specific thinking level\n  ${APP_NAME} --thinking high \"Solve this complex problem\"\n\n  # Read-only mode (no file modifications possible)\n  ${APP_NAME} --tools read,grep,find,ls -p \"Review the code in src/\"\n\n  # Export a session file to HTML\n  ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/agent/sessions/--path--/session.jsonl\n  ${APP_NAME} --export session.jsonl output.html\n\n${chalk.bold(\"Environment Variables:\")}\n  ANTHROPIC_API_KEY                - Anthropic Claude API key\n  ANTHROPIC_OAUTH_TOKEN            - Anthropic OAuth token (alternative to API key)\n  OPENAI_API_KEY                   - OpenAI GPT API key\n  AZURE_OPENAI_API_KEY             - Azure OpenAI API key\n  AZURE_OPENAI_BASE_URL            - Azure OpenAI base URL (https://{resource}.openai.azure.com/openai/v1)\n  AZURE_OPENAI_RESOURCE_NAME       - Azure OpenAI resource name (alternative to base URL)\n  AZURE_OPENAI_API_VERSION         - Azure OpenAI API version (default: v1)\n  AZURE_OPENAI_DEPLOYMENT_NAME_MAP - Azure OpenAI model=deployment map (comma-separated)\n  GEMINI_API_KEY                   - Google Gemini API key\n  GROQ_API_KEY                     - Groq API key\n  CEREBRAS_API_KEY                 - Cerebras API key\n  XAI_API_KEY                      - xAI Grok API key\n  OPENROUTER_API_KEY               - OpenRouter API key\n  AI_GATEWAY_API_KEY               - Vercel AI Gateway API key\n  ZAI_API_KEY                      - ZAI API key\n  MISTRAL_API_KEY                  - Mistral API key\n  MINIMAX_API_KEY                  - MiniMax API key\n  OPENCODE_API_KEY                 - OpenCode Zen/OpenCode Go API key\n  KIMI_API_KEY                     - Kimi For Coding API key\n  AWS_PROFILE                      - AWS profile for Amazon Bedrock\n  AWS_ACCESS_KEY_ID                - AWS access key for Amazon Bedrock\n  AWS_SECRET_ACCESS_KEY            - AWS secret key for Amazon Bedrock\n  AWS_BEARER_TOKEN_BEDROCK         - Bedrock API key (bearer token)\n  AWS_REGION                       - AWS region for Amazon Bedrock (e.g., us-east-1)\n  ${ENV_AGENT_DIR.padEnd(32)} - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)\n  PI_PACKAGE_DIR                   - Override package directory (for Nix/Guix store paths)\n  XCSH_OFFLINE                       - Disable startup network operations when set to 1/true/yes\n  XCSH_SHARE_VIEWER_URL              - Base URL for /share command (default: https://TODO.example.com/session/)\n  XCSH_AI_ANTIGRAVITY_VERSION        - Override Antigravity User-Agent version (e.g., 1.23.0)\n\n${chalk.bold(\"Available Tools (default: read, bash, edit, write):\")}\n  read   - Read file contents\n  bash   - Execute bash commands\n  edit   - Edit files with find/replace\n  write  - Write files (creates/overwrites)\n  grep   - Search file contents (read-only, off by default)\n  find   - Find files by glob pattern (read-only, off by default)\n  ls     - List directory contents (read-only, off by default)\n`);\n}\n"]}