flavor-code 1.2.1

package/dist/mcp/client.d.ts

@@ -0,0 +1,66 @@
+import type { McpServerConfig } from "../config/schema.js";
+import type { ToolDefinition } from "../tools/types.js";
+export interface McpRemoteTool {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface McpToolList {
+    tools: McpRemoteTool[];
+    nextCursor?: string;
+}
+export interface McpCallResult {
+    content?: unknown;
+    structuredContent?: unknown;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+export interface McpClientConnection {
+    listTools(params: {
+        cursor?: string;
+    }): Promise<McpToolList>;
+    callTool(params: {
+        name: string;
+        arguments: Record<string, unknown>;
+    }, options: {
+        signal: AbortSignal;
+        timeout: number;
+    }): Promise<McpCallResult>;
+    close(): Promise<void>;
+}
+export interface McpClientFactoryInput {
+    name: string;
+    config: McpServerConfig;
+    workspace: string;
+}
+export type McpClientFactory = (input: McpClientFactoryInput) => Promise<McpClientConnection>;
+export interface ConnectMcpServersOptions {
+    servers: Readonly<Record<string, McpServerConfig>>;
+    workspace: string;
+    clientFactory: McpClientFactory;
+}
+export type McpServerStatus = "connecting" | "connected" | "failed" | "disabled";
+export interface McpServerSummary {
+    name: string;
+    transport: "stdio" | "http";
+    status: McpServerStatus;
+    toolCount: number;
+    error?: string;
+}
+export interface McpManagedTool extends McpRemoteTool {
+    generatedName: string;
+}
+export declare class McpManager {
+    #private;
+    constructor(options: ConnectMcpServersOptions);
+    get tools(): readonly ToolDefinition<unknown>[];
+    get diagnostics(): readonly string[];
+    initialize(): Promise<void>;
+    listServers(): McpServerSummary[];
+    toolsFor(name: string): McpManagedTool[];
+    reconnect(name: string): Promise<McpServerSummary>;
+    setEnabled(name: string, enabled: boolean): Promise<McpServerSummary>;
+    close(): Promise<void>;
+}
+export declare function connectMcpServers(options: ConnectMcpServersOptions): Promise<McpManager>;
+export declare function mcpToolName(serverName: string, remoteName: string): string;

package/dist/mcp/sdk.d.ts

@@ -0,0 +1,27 @@
+import { type StdioServerParameters } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { type StreamableHTTPClientTransportOptions } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { McpClientConnection, McpClientFactoryInput, McpCallResult, McpToolList } from "./client.js";
+interface SdkClientLike {
+    connect(transport: unknown, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    listTools(params?: {
+        cursor?: string;
+    }): Promise<McpToolList>;
+    callTool(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }, resultSchema?: undefined, options?: {
+        signal?: AbortSignal;
+        timeout?: number;
+    }): Promise<McpCallResult>;
+    close(): Promise<void>;
+}
+export interface McpSdkDependencies {
+    createClient(): SdkClientLike;
+    createStdioTransport(options: StdioServerParameters): unknown;
+    createHttpTransport(url: URL, options: StreamableHTTPClientTransportOptions): unknown;
+    defaultEnvironment(): Record<string, string>;
+}
+export declare function connectSdkMcpClient(input: McpClientFactoryInput, dependencies?: McpSdkDependencies): Promise<McpClientConnection>;
+export {};

package/dist/memory/coordinator.d.ts

@@ -0,0 +1,32 @@
+import { type ModelMessage } from "../models/types.js";
+import type { ScoredMemoryCandidate } from "./types.js";
+export interface MemoryCoordinatorOptions {
+    review(taskId: string, candidates: readonly ScoredMemoryCandidate[]): void | Promise<void>;
+    remember(taskId: string, candidates: readonly ScoredMemoryCandidate[]): number | Promise<number>;
+    generate(prompt: string, signal: AbortSignal): Promise<string>;
+    minChars: number;
+    maxEntryChars: number;
+    scoreThreshold: number;
+    maxCandidates: number;
+    /** Candidates at or above this total score are stored directly without user review. Defaults to 11. */
+    autoStoreThreshold?: number;
+    language?: string;
+}
+export interface MemoryFinalizationResult {
+    evaluated: boolean;
+    candidates: boolean;
+    /** Number of candidates stored directly without review because they met the auto-store threshold. */
+    stored: number;
+}
+export interface ExplicitMemoryResult extends MemoryFinalizationResult {
+    stored: number;
+}
+export declare class MemoryCoordinator {
+    #private;
+    onError: ((error: unknown) => void) | undefined;
+    constructor(options: MemoryCoordinatorOptions);
+    finalize(taskId: string, messages: readonly ModelMessage[]): Promise<MemoryFinalizationResult>;
+    rememberExplicit(taskId: string, messages: readonly ModelMessage[]): Promise<ExplicitMemoryResult>;
+    flush(): Promise<void>;
+    abort(reason?: unknown): void;
+}

package/dist/memory/extractor.d.ts

@@ -0,0 +1,15 @@
+import type { ModelMessage } from "../models/types.js";
+import { type MemoryCandidate, type ScoredMemoryCandidate } from "./types.js";
+export declare function buildMemoryExtractionPrompt(messages: readonly ModelMessage[], options?: {
+    explicitIntent?: boolean;
+    outputLanguage?: string;
+    maxCandidates?: number;
+}): string;
+export declare function parseScoredMemoryCandidates(raw: string, options: {
+    maxEntryChars: number;
+    scoreThreshold: number;
+    maxCandidates: number;
+}): ScoredMemoryCandidate[];
+export declare function parseMemoryCandidates(raw: string, options: {
+    maxEntryChars: number;
+}): MemoryCandidate[];

package/dist/memory/intent.d.ts

@@ -0,0 +1,2 @@
+/** Detects an explicit request to persist memory; it does not decide what is safe to store. */
+export declare function isExplicitMemoryIntent(prompt: string): boolean;

package/dist/memory/retrieval.d.ts

@@ -0,0 +1,13 @@
+import type { MemoryHeat, MemoryReference } from "./types.js";
+export interface RankedMemoryReference {
+    reference: MemoryReference;
+    score: number;
+    heat: MemoryHeat;
+}
+export declare function classifyMemoryHeat(reference: MemoryReference, now?: Date): MemoryHeat;
+export declare function rankMemoryReferences(references: readonly MemoryReference[], query: string, options: {
+    now?: Date;
+    topK: number;
+    maxChars: number;
+    minScore?: number;
+}): RankedMemoryReference[];

package/dist/memory/review.d.ts

@@ -0,0 +1,36 @@
+import type { MemoryCandidate, MemoryScores, ScoredMemoryCandidate } from "./types.js";
+export interface MemoryReviewItem extends MemoryCandidate {
+    id: string;
+    taskId?: string;
+    summary?: string;
+    topicKey?: string;
+    keywords?: string[];
+    scores?: MemoryScores;
+}
+export interface MemoryReviewBridgeOptions {
+    remember(candidate: MemoryReviewItem): Promise<unknown>;
+    onChange?(): void;
+    /** Called after a candidate is explicitly dismissed by the user. */
+    onDismiss?(): void;
+    /** Called after a candidate is accepted and stored. */
+    onAccept?(): void;
+    /**
+     * Seconds an unconfirmed candidate stays pending before it is silently
+     * dismissed. 0 (the default) disables the auto-dismiss timer. A timeout is
+     * not an explicit user dismissal and never triggers {@link onDismiss}.
+     */
+    autoDismissSeconds?: number;
+}
+/** Holds model-generated memory outside the durable store until the user accepts it. */
+export declare class MemoryReviewBridge {
+    #private;
+    readonly autoDismissSeconds: number;
+    constructor(options: MemoryReviewBridgeOptions);
+    get pending(): readonly MemoryReviewItem[];
+    offer(candidates: readonly MemoryCandidate[]): number;
+    offer(taskId: string, candidates: readonly ScoredMemoryCandidate[]): number;
+    accept(id: string): Promise<boolean>;
+    dismiss(id: string): boolean;
+    dismissAll(): number;
+    dispose(): void;
+}

package/dist/memory/similarity.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeForSimilarity(value: string): string;
+export declare function jaccard(left: ReadonlySet<string>, right: ReadonlySet<string>): number;
+export declare function wordTokens(value: string): Set<string>;
+export declare function characterNgrams(value: string, size?: number): Set<string>;
+export declare function memorySimilarity(left: string, right: string): number;

package/dist/memory/store.d.ts

@@ -0,0 +1,58 @@
+import { type MemoryCandidate, type MemoryEntry, type MemoryReference, type ScoredMemoryCandidate } from "./types.js";
+export { MEMORY_TYPES } from "./types.js";
+export type { MemoryCandidate, MemoryEntry, MemoryType } from "./types.js";
+export interface MemoryStoreOptions {
+    workspace: string;
+    maxEntries: number;
+    maxEntryChars: number;
+}
+/** Cross-session state learned from how the user handles generated review candidates. */
+export interface MemoryBehavior {
+    /** Consecutive explicit dismissals of review candidates without any acceptance. */
+    ignoreStreak: number;
+    /** Auto-extraction paused after the ignore streak reached the configured limit. */
+    autoExtractPaused: boolean;
+}
+export declare const DEFAULT_MEMORY_BEHAVIOR: MemoryBehavior;
+export declare class MemoryStore {
+    #private;
+    readonly workspace: string;
+    readonly path: string;
+    constructor(options: MemoryStoreOptions);
+    loadBehavior(): Promise<MemoryBehavior>;
+    saveBehavior(behavior: MemoryBehavior): Promise<void>;
+    references(): Promise<MemoryReference[]>;
+    list(): Promise<MemoryEntry[]>;
+    userContext(): Promise<string | undefined>;
+    remember(candidate: MemoryCandidate): Promise<{
+        entry: MemoryEntry;
+        added: boolean;
+    }>;
+    rememberForTask(taskId: string, candidate: ScoredMemoryCandidate, now?: Date): Promise<{
+        entry: MemoryEntry;
+        added: boolean;
+    }>;
+    rememberMany(candidates: readonly MemoryCandidate[]): Promise<{
+        added: number;
+        skipped: number;
+    }>;
+    update(id: string, candidate: MemoryCandidate): Promise<MemoryEntry>;
+    delete(id: string): Promise<boolean>;
+    forget(query: string): Promise<number>;
+    recall(query: string, options: {
+        taskId: string;
+        topK: number;
+        maxChars: number;
+        now?: Date;
+    }): Promise<{
+        context?: string;
+        references: readonly MemoryReference[];
+    }>;
+}
+export declare function parseMemoryDocument(raw: string, maxEntryChars: number): MemoryEntry[];
+/** Human-readable view used by management commands, not the V2 storage codec. */
+export declare function renderMemoryDocument(entries: readonly MemoryEntry[]): string;
+export declare function formatMemoryContext(entries: readonly MemoryEntry[], maxChars: number): string | undefined;
+export declare function validateCandidate(candidate: MemoryCandidate, maxEntryChars: number): MemoryEntry;
+export declare function normalizeMemoryContent(content: string): string;
+export declare function containsSensitiveMemory(content: string): boolean;

package/dist/memory/types.d.ts

@@ -0,0 +1,37 @@
+export declare const MEMORY_TYPES: readonly ["user", "feedback", "project", "reference"];
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+export interface MemoryCandidate {
+    type: MemoryType;
+    content: string;
+}
+export interface MemoryEntry extends MemoryCandidate {
+    id: string;
+}
+export interface MemoryScores {
+    durability: number;
+    futureUtility: number;
+    authority: number;
+    nonDerivability: number;
+}
+export interface ScoredMemoryCandidate extends MemoryCandidate {
+    summary: string;
+    topicKey: string;
+    keywords: string[];
+    scores: MemoryScores;
+}
+export interface MemoryReference {
+    id: string;
+    type: MemoryType;
+    taskId: string;
+    summary: string;
+    contentPath: string;
+    topicKey: string;
+    keywords: string[];
+    createdAt: string;
+    updatedAt: string;
+    recallTotal: number;
+    /** One timestamp per distinct recalling task. */
+    recalls: Record<string, string>;
+    relatedTo?: string[];
+}
+export type MemoryHeat = "hot" | "cold" | "normal";

package/dist/models/anthropic.d.ts

@@ -0,0 +1,24 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type { MessageCreateParamsStreaming, RawMessageStreamEvent } from "@anthropic-ai/sdk/resources/messages/messages.js";
+import { type ModelAdapter, type ModelEvent, type ModelRequest } from "./types.js";
+export interface AnthropicClient {
+    messages: {
+        create(body: MessageCreateParamsStreaming, options?: Anthropic.RequestOptions): AsyncIterable<RawMessageStreamEvent> | PromiseLike<AsyncIterable<RawMessageStreamEvent>>;
+    };
+}
+export interface AnthropicModelAdapterOptions {
+    apiKey?: string;
+    baseURL?: string;
+    client?: AnthropicClient;
+    maxOutputTokens?: number;
+    /** Mirror the per-request cache breakdown to stderr. Defaults to FLAVOR_DEBUG_USAGE=1. File logging to usage.jsonl is always on. */
+    debugUsage?: boolean;
+}
+export declare class AnthropicModelAdapter implements ModelAdapter {
+    #private;
+    private readonly client;
+    private readonly maxOutputTokens;
+    private readonly debugUsage;
+    constructor(options: AnthropicModelAdapterOptions);
+    stream(request: ModelRequest): AsyncIterable<ModelEvent>;
+}

package/dist/models/cache-profile.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Intelligent cache-capability identification for model providers.
+ *
+ * Provider protocol (`apiType`) is read from the project `.flavor/flavor.json`
+ * (or the PKCE token `llm_config`); combined with `baseURL` heuristics it
+ * decides which prompt-cache strategy applies so the runtime can surface
+ * accurate diagnostics instead of assuming every endpoint caches like
+ * Anthropic.
+ */
+export type CacheStrategy = "explicit" | "implicit" | "none";
+export interface CacheProfileInput {
+    apiType?: string | undefined;
+    baseURL?: string | undefined;
+}
+export interface CacheProfile {
+    strategy: CacheStrategy;
+    /** Whether client-side cache markers (cache_control breakpoints) are honored. */
+    markersSupported: boolean;
+    reason: string;
+}
+/** True when the baseURL points at an Alibaba Cloud DashScope / MaaS gateway. */
+export declare function isDashScopeBaseURL(baseURL: string | undefined): boolean;
+export declare function resolveCacheProfile(input: CacheProfileInput): CacheProfile;

package/dist/models/openai.d.ts

@@ -0,0 +1,24 @@
+import OpenAI from "openai";
+import type { ResponseStreamEvent } from "openai/resources/responses/responses.js";
+import { type ModelAdapter, type ModelEvent, type ModelRequest } from "./types.js";
+type OpenAIStreamRequest = Parameters<OpenAI["responses"]["stream"]>[0];
+export interface OpenAIClient {
+    responses: {
+        stream(body: OpenAIStreamRequest, options?: OpenAI.RequestOptions): AsyncIterable<ResponseStreamEvent>;
+    };
+}
+export interface OpenAIModelAdapterOptions {
+    apiKey?: string;
+    baseURL?: string;
+    client?: OpenAIClient;
+    /** Mirror the per-request cache breakdown to stderr. Defaults to FLAVOR_DEBUG_USAGE=1. File logging to usage.jsonl is always on. */
+    debugUsage?: boolean;
+}
+export declare class OpenAIModelAdapter implements ModelAdapter {
+    #private;
+    private readonly client;
+    private readonly debugUsage;
+    constructor(options: OpenAIModelAdapterOptions);
+    stream(request: ModelRequest): AsyncIterable<ModelEvent>;
+}
+export {};

package/dist/models/registry.d.ts

@@ -0,0 +1,16 @@
+import type { ModelAdapter } from "./types.js";
+export interface ParsedModelId {
+    provider: string;
+    model: string;
+}
+export declare function parseModelId(id: string): ParsedModelId;
+export declare class ModelRegistry {
+    private readonly adapters;
+    register(provider: string, adapter: ModelAdapter): this;
+    has(provider: string): boolean;
+    unregister(provider: string, adapter?: ModelAdapter): boolean;
+    get(id: string): {
+        adapter: ModelAdapter;
+        model: string;
+    };
+}

package/dist/models/structured.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import type { ModelRegistry } from "./registry.js";
+import type { ModelMessage, ModelTool, ProviderError } from "./types.js";
+export interface StructuredOutputRetryPolicy {
+    maxRetries: number;
+    backoffMs: readonly number[];
+}
+export interface StructuredOutputOptions<T> {
+    registry: ModelRegistry;
+    modelId: string;
+    name: string;
+    description: string;
+    schema: z.ZodType<T>;
+    retry?: StructuredOutputRetryPolicy;
+    beforeAttempt?(attempt: StructuredOutputAttempt): void | Promise<void>;
+    afterAttempt?(attempt: StructuredOutputAttemptResult): void | Promise<void>;
+}
+export interface StructuredOutputAttempt {
+    modelId: string;
+    attempt: number;
+    maxAttempts: number;
+    messageCount: number;
+}
+export interface StructuredOutputAttemptResult extends StructuredOutputAttempt {
+    completed: boolean;
+    error?: ProviderError;
+}
+export interface StructuredOutputRequest {
+    messages: ModelMessage[];
+    invalidOutput?: string;
+    validationError?: string;
+    signal?: AbortSignal;
+}
+export type StructuredOutputEvent<T> = {
+    type: "attempt-start";
+    attempt: number;
+    maxAttempts: number;
+} | {
+    type: "attempt-end";
+    attempt: number;
+    maxAttempts: number;
+} | {
+    type: "usage";
+    inputTokens: number;
+    outputTokens: number;
+} | {
+    type: "retry";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    error: string;
+} | {
+    type: "output";
+    value: T;
+    attempts: number;
+};
+export interface StructuredOutputResult<T> {
+    value: T;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    attempts: number;
+}
+export interface StructuredModel<T> {
+    stream(request: StructuredOutputRequest): AsyncIterable<StructuredOutputEvent<T>>;
+    invoke(request: StructuredOutputRequest): Promise<StructuredOutputResult<T>>;
+}
+export declare class StructuredOutputError extends Error {
+    readonly code: "structured_output_error";
+    constructor(message: string);
+}
+export declare function withStructuredOutput<T>(options: StructuredOutputOptions<T>): StructuredModel<T>;
+export declare function strictJsonSchema(schema: z.ZodType<unknown>): Record<string, unknown>;
+export declare function modelToolFromZod(name: string, description: string, schema: z.ZodType<unknown>): ModelTool;

package/dist/models/types.d.ts

@@ -0,0 +1,93 @@
+export type ModelImageMediaType = "image/png" | "image/jpeg" | "image/webp";
+export interface ModelTextContentBlock {
+    type: "text";
+    text: string;
+}
+export interface ModelImageContentBlock {
+    type: "image";
+    source: {
+        type: "file";
+        path: string;
+    };
+    mediaType: ModelImageMediaType;
+    sha256: string;
+    bytes: number;
+    name?: string | undefined;
+}
+export type ModelContentBlock = ModelTextContentBlock | ModelImageContentBlock;
+export type ModelContent = string | ModelContentBlock[];
+interface ModelMessageMetadata {
+    toolCallId?: string;
+    toolCalls?: ModelToolCall[];
+    /** Provider-neutral marker for the end of a byte-stable reusable prompt prefix. */
+    cacheBreakpoint?: boolean;
+}
+export type ModelMessage = (ModelMessageMetadata & {
+    role: "user";
+    content: ModelContent;
+}) | (ModelMessageMetadata & {
+    role: "system" | "assistant" | "tool";
+    content: string;
+});
+export declare function modelContentText(content: ModelContent): string;
+export declare function modelContentTranscriptText(content: ModelContent): string;
+export declare function cloneModelContent(content: ModelContent): ModelContent;
+export interface ModelToolCall {
+    id: string;
+    name: string;
+    input: unknown;
+}
+export interface ModelTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    strict?: boolean;
+}
+export interface ModelRequest {
+    model: string;
+    messages: ModelMessage[];
+    tools: ModelTool[];
+    signal?: AbortSignal;
+}
+export type ProviderErrorCode = "authentication" | "rate_limit" | "context_overflow" | "output_limit" | "model_not_found" | "network" | "cancelled" | "invalid_tool_arguments" | "structured_output_error" | "unknown";
+export interface ProviderError {
+    code: ProviderErrorCode;
+    message: string;
+}
+export type ModelEvent = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool-call";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "invalid-tool-call";
+    id: string;
+    name: string;
+    rawInput: string;
+    error: ProviderError;
+} | {
+    type: "usage";
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+} | {
+    type: "error";
+    error: ProviderError;
+} | {
+    type: "done";
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens?: number;
+        cacheCreationTokens?: number;
+    };
+};
+export interface ModelAdapter {
+    stream(request: ModelRequest): AsyncIterable<ModelEvent>;
+}
+export declare function normalizeProviderError(error: unknown): ProviderError;
+export {};

package/dist/permissions/classifier.d.ts

@@ -0,0 +1,9 @@
+import type { ModelRegistry } from "../models/registry.js";
+import type { PermissionDecision, PermissionRequest } from "./engine.js";
+export type PermissionClassifier = (request: PermissionRequest, signal: AbortSignal) => Promise<PermissionDecision>;
+export interface PermissionClassifierOptions {
+    registry: ModelRegistry;
+    modelId(): string;
+    timeoutMs?: number;
+}
+export declare function createPermissionClassifier(options: PermissionClassifierOptions): PermissionClassifier;

package/dist/permissions/engine.d.ts

@@ -0,0 +1,28 @@
+import { type LegacyPermissionMode, type PermissionMode } from "../config/schema.js";
+export type { PermissionMode } from "../config/schema.js";
+export type PermissionDecision = {
+    decision: "allow" | "deny" | "ask";
+    reason?: string;
+};
+export interface PermissionRequest {
+    agent: "main" | "subagent";
+    tool: string;
+    paths?: readonly string[];
+    command?: string;
+    args?: readonly string[];
+    cwd?: string;
+}
+export interface PermissionEngineOptions {
+    workspace: string;
+    mode?: PermissionMode | LegacyPermissionMode;
+}
+export type ToolCategory = "control" | "read" | "write" | "destructive" | "shell" | "network" | "unknown";
+export declare function getToolCategory(name: string): ToolCategory;
+export declare function isDestructiveTool(name: string): boolean;
+export declare class PermissionEngine {
+    #private;
+    constructor(options: PermissionEngineOptions);
+    get mode(): PermissionMode;
+    setMode(mode: PermissionMode | LegacyPermissionMode): void;
+    decide(request: PermissionRequest): PermissionDecision;
+}

package/dist/plugins/host.d.ts

@@ -0,0 +1,15 @@
+import type { LoadedPlugin, PluginDiagnostic, PluginHostOptions } from "./types.js";
+/**
+ * Hosts trusted in-process plugins behind a narrow host API. Plugin roots must remain immutable
+ * during activation. Concurrent malicious mutation is outside the MVP trust model because plugin
+ * code already has Node.js authority; this is explicitly not a process sandbox.
+ */
+export declare class PluginHost {
+    #private;
+    constructor(options: PluginHostOptions);
+    get diagnostics(): readonly PluginDiagnostic[];
+    get loadedPlugins(): readonly LoadedPlugin[];
+    loadAll(): Promise<void>;
+    unloadAll(): Promise<void>;
+    unload(name: string): Promise<void>;
+}