@fabriccode/weave 0.7.0

package/dist/agents/types.d.ts

@@ -0,0 +1,82 @@
+import type { AgentConfig } from "@fabriccode/sdk";
+/**
+ * Agent mode determines UI model selection behavior:
+ * - "primary": Respects user's UI-selected model (loom, tapestry)
+ * - "subagent": Uses own fallback chain, ignores UI selection (pattern, thread, spindle)
+ * - "all": Available in both contexts (shuttle)
+ */
+export type AgentMode = "primary" | "subagent" | "all";
+/**
+ * Agent factory function with static mode property.
+ * Mode is exposed as static property for pre-instantiation access.
+ */
+export type AgentFactory = ((model: string) => AgentConfig) & {
+    mode: AgentMode;
+};
+/**
+ * Agent source is either a factory (called with model) or a static config (cloned)
+ */
+export type AgentSource = AgentFactory | AgentConfig;
+/**
+ * Agent category for grouping in Loom prompt sections
+ */
+export type AgentCategory = "exploration" | "specialist" | "advisor" | "utility";
+/**
+ * Cost classification for Tool Selection table
+ */
+export type AgentCost = "FREE" | "CHEAP" | "EXPENSIVE";
+/**
+ * Delegation trigger for Loom prompt's Delegation Table
+ */
+export interface DelegationTrigger {
+    /** Domain of work (e.g., "Frontend UI/UX") */
+    domain: string;
+    /** When to delegate (e.g., "Visual changes only...") */
+    trigger: string;
+}
+/**
+ * Metadata for generating Loom prompt sections dynamically.
+ * Allows adding/removing agents without manually updating the Loom prompt.
+ */
+export interface AgentPromptMetadata {
+    /** Category for grouping in prompt sections */
+    category: AgentCategory;
+    /** Cost classification for Tool Selection table */
+    cost: AgentCost;
+    /** Domain triggers for Delegation Table */
+    triggers: DelegationTrigger[];
+    /** When to use this agent (for detailed sections) */
+    useWhen?: string[];
+    /** When NOT to use this agent */
+    avoidWhen?: string[];
+    /** Optional dedicated prompt section (markdown) */
+    dedicatedSection?: string;
+    /** Nickname/alias used in prompt (e.g., "Pattern" instead of "pattern") */
+    promptAlias?: string;
+    /** Key trigger that should appear in Phase 0 quick checks */
+    keyTrigger?: string;
+}
+/**
+ * The 8 built-in Weave agent names
+ */
+export type WeaveAgentName = "loom" | "tapestry" | "shuttle" | "pattern" | "thread" | "spindle" | "weft" | "warp";
+/**
+ * Override config for a single agent — all fields optional
+ */
+export type AgentOverrideConfig = Partial<AgentConfig> & {
+    prompt_append?: string;
+    variant?: string;
+    fallback_models?: string | string[];
+};
+/**
+ * Map of agent name to override config
+ */
+export type AgentOverrides = Partial<Record<WeaveAgentName, AgentOverrideConfig>>;
+/**
+ * Returns true if the model string identifies a GPT/OpenAI model.
+ */
+export declare function isGptModel(model: string): boolean;
+/**
+ * Type guard: returns true if source is an AgentFactory (callable with .mode).
+ */
+export declare function isFactory(source: AgentSource): source is AgentFactory;

package/dist/agents/warp/default.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@fabriccode/sdk";
+export declare const WARP_DEFAULTS: AgentConfig;

package/dist/agents/warp/index.d.ts

@@ -0,0 +1,2 @@
+import type { AgentFactory } from "../types";
+export declare const createWarpAgent: AgentFactory;

package/dist/agents/weft/default.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@fabriccode/sdk";
+export declare const WEFT_DEFAULTS: AgentConfig;

package/dist/agents/weft/index.d.ts

@@ -0,0 +1,2 @@
+import type { AgentFactory } from "../types";
+export declare const createWeftAgent: AgentFactory;

package/dist/config/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./schema";
+export { loadWeaveConfig } from "./loader";
+export { mergeConfigs } from "./merge";

package/dist/config/loader.d.ts

@@ -0,0 +1,2 @@
+import { type WeaveConfig } from "./schema";
+export declare function loadWeaveConfig(directory: string, _ctx?: unknown, _homeDir?: string): WeaveConfig;

package/dist/config/merge.d.ts

@@ -0,0 +1,3 @@
+import type { WeaveConfig } from "./schema";
+import type { DeepPartial } from "../shared/types";
+export declare function mergeConfigs(user: DeepPartial<WeaveConfig>, project: DeepPartial<WeaveConfig>): DeepPartial<WeaveConfig>;

package/dist/config/schema.d.ts

@@ -0,0 +1,274 @@
+import { z } from "zod";
+export declare const AgentOverrideConfigSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    fallback_models: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    variant: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    top_p: z.ZodOptional<z.ZodNumber>;
+    prompt: z.ZodOptional<z.ZodString>;
+    prompt_append: z.ZodOptional<z.ZodString>;
+    tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    disable: z.ZodOptional<z.ZodBoolean>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        subagent: "subagent";
+        primary: "primary";
+        all: "all";
+    }>>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const AgentOverridesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    fallback_models: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    variant: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    top_p: z.ZodOptional<z.ZodNumber>;
+    prompt: z.ZodOptional<z.ZodString>;
+    prompt_append: z.ZodOptional<z.ZodString>;
+    tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    disable: z.ZodOptional<z.ZodBoolean>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        subagent: "subagent";
+        primary: "primary";
+        all: "all";
+    }>>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const CategoryConfigSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    fallback_models: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    variant: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    top_p: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    prompt_append: z.ZodOptional<z.ZodString>;
+    disable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const CategoriesConfigSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    fallback_models: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    variant: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    top_p: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    prompt_append: z.ZodOptional<z.ZodString>;
+    disable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>>;
+export declare const BackgroundConfigSchema: z.ZodObject<{
+    defaultConcurrency: z.ZodOptional<z.ZodNumber>;
+    providerConcurrency: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    modelConcurrency: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    staleTimeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const TmuxConfigSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    layout: z.ZodOptional<z.ZodEnum<{
+        "main-horizontal": "main-horizontal";
+        "main-vertical": "main-vertical";
+        tiled: "tiled";
+        "even-horizontal": "even-horizontal";
+        "even-vertical": "even-vertical";
+    }>>;
+    main_pane_size: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const ExperimentalConfigSchema: z.ZodObject<{
+    plugin_load_timeout_ms: z.ZodOptional<z.ZodNumber>;
+    context_window_warning_threshold: z.ZodOptional<z.ZodNumber>;
+    context_window_critical_threshold: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const DelegationTriggerSchema: z.ZodObject<{
+    domain: z.ZodString;
+    trigger: z.ZodString;
+}, z.core.$strip>;
+export declare const CustomAgentConfigSchema: z.ZodObject<{
+    prompt: z.ZodOptional<z.ZodString>;
+    prompt_file: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    display_name: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        subagent: "subagent";
+        primary: "primary";
+        all: "all";
+    }>>;
+    fallback_models: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    category: z.ZodOptional<z.ZodEnum<{
+        exploration: "exploration";
+        specialist: "specialist";
+        advisor: "advisor";
+        utility: "utility";
+    }>>;
+    cost: z.ZodOptional<z.ZodEnum<{
+        FREE: "FREE";
+        CHEAP: "CHEAP";
+        EXPENSIVE: "EXPENSIVE";
+    }>>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    top_p: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    triggers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        domain: z.ZodString;
+        trigger: z.ZodString;
+    }, z.core.$strip>>>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const CustomAgentsConfigSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    prompt: z.ZodOptional<z.ZodString>;
+    prompt_file: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    display_name: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        subagent: "subagent";
+        primary: "primary";
+        all: "all";
+    }>>;
+    fallback_models: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    category: z.ZodOptional<z.ZodEnum<{
+        exploration: "exploration";
+        specialist: "specialist";
+        advisor: "advisor";
+        utility: "utility";
+    }>>;
+    cost: z.ZodOptional<z.ZodEnum<{
+        FREE: "FREE";
+        CHEAP: "CHEAP";
+        EXPENSIVE: "EXPENSIVE";
+    }>>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    top_p: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    triggers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        domain: z.ZodString;
+        trigger: z.ZodString;
+    }, z.core.$strip>>>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export declare const AnalyticsConfigSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    use_fingerprint: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const WorkflowConfigSchema: z.ZodObject<{
+    disabled_workflows: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const WeaveConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    agents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        fallback_models: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        variant: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        top_p: z.ZodOptional<z.ZodNumber>;
+        prompt: z.ZodOptional<z.ZodString>;
+        prompt_append: z.ZodOptional<z.ZodString>;
+        tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+        disable: z.ZodOptional<z.ZodBoolean>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            subagent: "subagent";
+            primary: "primary";
+            all: "all";
+        }>>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    custom_agents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        prompt: z.ZodOptional<z.ZodString>;
+        prompt_file: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        display_name: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            subagent: "subagent";
+            primary: "primary";
+            all: "all";
+        }>>;
+        fallback_models: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        category: z.ZodOptional<z.ZodEnum<{
+            exploration: "exploration";
+            specialist: "specialist";
+            advisor: "advisor";
+            utility: "utility";
+        }>>;
+        cost: z.ZodOptional<z.ZodEnum<{
+            FREE: "FREE";
+            CHEAP: "CHEAP";
+            EXPENSIVE: "EXPENSIVE";
+        }>>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        top_p: z.ZodOptional<z.ZodNumber>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        triggers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            domain: z.ZodString;
+            trigger: z.ZodString;
+        }, z.core.$strip>>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    categories: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        fallback_models: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        variant: z.ZodOptional<z.ZodString>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        top_p: z.ZodOptional<z.ZodNumber>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+        prompt_append: z.ZodOptional<z.ZodString>;
+        disable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    disabled_hooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disabled_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disabled_agents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disabled_skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    background: z.ZodOptional<z.ZodObject<{
+        defaultConcurrency: z.ZodOptional<z.ZodNumber>;
+        providerConcurrency: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        modelConcurrency: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        staleTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    analytics: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        use_fingerprint: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    tmux: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        layout: z.ZodOptional<z.ZodEnum<{
+            "main-horizontal": "main-horizontal";
+            "main-vertical": "main-vertical";
+            tiled: "tiled";
+            "even-horizontal": "even-horizontal";
+            "even-vertical": "even-vertical";
+        }>>;
+        main_pane_size: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    experimental: z.ZodOptional<z.ZodObject<{
+        plugin_load_timeout_ms: z.ZodOptional<z.ZodNumber>;
+        context_window_warning_threshold: z.ZodOptional<z.ZodNumber>;
+        context_window_critical_threshold: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    workflows: z.ZodOptional<z.ZodObject<{
+        disabled_workflows: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AgentOverrideConfig = z.infer<typeof AgentOverrideConfigSchema>;
+export type AgentOverrides = z.infer<typeof AgentOverridesSchema>;
+export type CustomAgentConfig = z.infer<typeof CustomAgentConfigSchema>;
+export type CustomAgentsConfig = z.infer<typeof CustomAgentsConfigSchema>;
+export type CategoryConfig = z.infer<typeof CategoryConfigSchema>;
+export type CategoriesConfig = z.infer<typeof CategoriesConfigSchema>;
+export type BackgroundConfig = z.infer<typeof BackgroundConfigSchema>;
+export type AnalyticsConfig = z.infer<typeof AnalyticsConfigSchema>;
+export type TmuxConfig = z.infer<typeof TmuxConfigSchema>;
+export type ExperimentalConfig = z.infer<typeof ExperimentalConfigSchema>;
+export type WorkflowConfig = z.infer<typeof WorkflowConfigSchema>;
+export type WeaveConfig = z.infer<typeof WeaveConfigSchema>;

package/dist/create-managers.d.ts

@@ -0,0 +1,21 @@
+import type { PluginInput } from "@fabriccode/plugin";
+import type { AgentConfig } from "@fabriccode/sdk";
+import type { WeaveConfig } from "./config/schema";
+import type { ResolveSkillsFn } from "./agents/agent-builder";
+import type { ProjectFingerprint } from "./features/analytics/types";
+import { ConfigHandler } from "./managers/config-handler";
+import { BackgroundManager } from "./managers/background-manager";
+import { SkillMcpManager } from "./managers/skill-mcp-manager";
+export interface WeaveManagers {
+    configHandler: ConfigHandler;
+    backgroundManager: BackgroundManager;
+    skillMcpManager: SkillMcpManager;
+    agents: Record<string, AgentConfig>;
+}
+export declare function createManagers(options: {
+    ctx: PluginInput;
+    pluginConfig: WeaveConfig;
+    resolveSkills?: ResolveSkillsFn;
+    fingerprint?: ProjectFingerprint | null;
+    configDir?: string;
+}): WeaveManagers;

package/dist/create-tools.d.ts

@@ -0,0 +1,16 @@
+import type { PluginInput } from "@fabriccode/plugin";
+import type { WeaveConfig } from "./config/schema";
+import type { WeaveManagers } from "./create-managers";
+import type { ToolsRecord } from "./plugin/types";
+import type { LoadedSkill } from "./features/skill-loader/types";
+import type { ResolveSkillsFn } from "./agents/agent-builder";
+export interface ToolsResult {
+    tools: ToolsRecord;
+    availableSkills: LoadedSkill[];
+    resolveSkillsFn: ResolveSkillsFn;
+}
+export declare function createTools(options: {
+    ctx: PluginInput;
+    pluginConfig: WeaveConfig;
+    managers?: WeaveManagers;
+}): Promise<ToolsResult>;

package/dist/features/analytics/adherence.d.ts

@@ -0,0 +1,10 @@
+import type { AdherenceReport } from "./types";
+/**
+ * Calculate plan adherence by comparing planned vs actual file changes.
+ *
+ * - **coverage**: fraction of planned files that were actually changed (0-1).
+ *   If no files were planned, coverage = 1 (vacuously complete).
+ * - **precision**: fraction of actual changes that were planned (0-1).
+ *   If no files were changed, precision = 1 (vacuously precise).
+ */
+export declare function calculateAdherence(plannedFiles: string[], actualFiles: string[]): AdherenceReport;

package/dist/features/analytics/fingerprint.d.ts

@@ -0,0 +1,33 @@
+import type { ProjectFingerprint, DetectedStack } from "./types";
+/**
+ * Detect the technology stack of a project by scanning for marker files.
+ * This is a fast, synchronous scan — suitable for fire-and-forget use.
+ */
+export declare function detectStack(directory: string): DetectedStack[];
+/**
+ * Detect the package manager used by the project.
+ */
+export declare function detectPackageManager(directory: string): string | undefined;
+/**
+ * Detect whether the project is a monorepo.
+ */
+export declare function detectMonorepo(directory: string): boolean;
+/**
+ * Detect the primary language of the project.
+ */
+export declare function detectPrimaryLanguage(stack: DetectedStack[]): string | undefined;
+/**
+ * Generate a complete project fingerprint.
+ */
+export declare function generateFingerprint(directory: string): ProjectFingerprint;
+/**
+ * Generate and persist a project fingerprint.
+ * Fire-and-forget: errors are logged but never thrown.
+ */
+export declare function fingerprintProject(directory: string): ProjectFingerprint | null;
+/**
+ * Get the cached fingerprint, or generate a new one if missing or stale.
+ * Regenerates if the cached fingerprint was generated by a different Weave version.
+ * Fire-and-forget: errors are logged but never thrown.
+ */
+export declare function getOrCreateFingerprint(directory: string): ProjectFingerprint | null;

package/dist/features/analytics/format-metrics.d.ts

@@ -0,0 +1,10 @@
+import type { MetricsReport, SessionSummary } from "./types";
+/**
+ * Format metrics reports and session summaries into a markdown dashboard.
+ *
+ * @param reports - Array of MetricsReport from readMetricsReports()
+ * @param summaries - Array of SessionSummary from readSessionSummaries()
+ * @param args - Optional arguments: a plan name to filter, "all" for all reports, or empty for last 5
+ * @returns Formatted markdown string
+ */
+export declare function formatMetricsMarkdown(reports: MetricsReport[], summaries: SessionSummary[], args?: string): string;

package/dist/features/analytics/generate-metrics-report.d.ts

@@ -0,0 +1,17 @@
+import type { WorkState } from "../work-state/types";
+import type { MetricsReport } from "./types";
+/**
+ * Generate a Phase 1 metrics report for a completed plan.
+ *
+ * Orchestrates:
+ * 1. Extract planned files from the plan markdown
+ * 2. Get actual changed files via git diff (startSha..HEAD)
+ * 3. Calculate adherence (coverage, precision)
+ * 4. Aggregate token usage across all sessions for this plan
+ * 5. Compute total duration from session summaries
+ * 6. Write the report to metrics-reports.jsonl
+ *
+ * In Phase 1, `quality` and `gaps` are undefined.
+ * Returns the report if successful, null on error.
+ */
+export declare function generateMetricsReport(directory: string, state: WorkState): MetricsReport | null;

package/dist/features/analytics/git-diff.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Get the list of files changed between a given SHA and HEAD.
+ *
+ * Uses `git diff --name-only fromSha..HEAD` and returns relative paths.
+ * Returns an empty array on any error (non-git repo, invalid SHA, etc.).
+ */
+export declare function getChangedFiles(directory: string, fromSha: string): string[];

package/dist/features/analytics/index.d.ts

@@ -0,0 +1,29 @@
+export type { ToolUsageEntry, DelegationEntry, SessionSummary, TokenUsage, MetricsTokenUsage, AdherenceReport, MetricsReport, DetectedStack, ProjectFingerprint, Suggestion, InFlightToolCall, TrackedSession, } from "./types";
+export { ANALYTICS_DIR, SESSION_SUMMARIES_FILE, FINGERPRINT_FILE, METRICS_REPORTS_FILE, MAX_METRICS_ENTRIES, zeroTokenUsage, } from "./types";
+export { ensureAnalyticsDir, appendSessionSummary, readSessionSummaries, writeFingerprint, readFingerprint, writeMetricsReport, readMetricsReports, } from "./storage";
+export { detectStack, detectPackageManager, detectMonorepo, detectPrimaryLanguage, generateFingerprint, fingerprintProject, getOrCreateFingerprint, } from "./fingerprint";
+export { SessionTracker, createSessionTracker } from "./session-tracker";
+export { generateSuggestions, getSuggestionsForProject } from "./suggestions";
+export { generateTokenReport, getTokenReport } from "./token-report";
+export { formatMetricsMarkdown } from "./format-metrics";
+export { generateMetricsReport } from "./generate-metrics-report";
+export { extractPlannedFiles } from "./plan-parser";
+export { getChangedFiles } from "./git-diff";
+export { calculateAdherence } from "./adherence";
+export { aggregateTokensForPlan } from "./plan-token-aggregator";
+import type { SessionTracker } from "./session-tracker";
+import type { ProjectFingerprint } from "./types";
+/** Return value of createAnalytics — bundles tracker + fingerprint */
+export interface Analytics {
+    /** Session tracker instance — wire into tool.execute.before/after */
+    tracker: SessionTracker;
+    /** Project fingerprint (may be null if detection fails) */
+    fingerprint: ProjectFingerprint | null;
+}
+/**
+ * Create all analytics services for a project.
+ * Instantiates the session tracker and uses the provided fingerprint (if any).
+ * Fingerprint generation is the caller's responsibility — pass null to opt out.
+ * This is the single entry point called from the plugin's main init.
+ */
+export declare function createAnalytics(directory: string, fingerprint: ProjectFingerprint | null): Analytics;

package/dist/features/analytics/plan-parser.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Extract all planned file paths from a plan's `## TODOs` section.
+ *
+ * Parses `**Files**:` lines, splits on commas, strips `(new)` / `Create` prefixes,
+ * deduplicates, and returns normalized relative paths.
+ */
+export declare function extractPlannedFiles(planPath: string): string[];

package/dist/features/analytics/plan-token-aggregator.d.ts

@@ -0,0 +1,11 @@
+import type { MetricsTokenUsage } from "./types";
+/**
+ * Aggregate token usage for a plan by summing across matching session summaries.
+ *
+ * Reads all session summaries, filters to those whose `sessionId` is in `sessionIds`,
+ * and sums their `tokenUsage` fields. Sessions without `tokenUsage` contribute zeros
+ * (backward compatibility).
+ *
+ * Maps from session TokenUsage (inputTokens/outputTokens) to MetricsTokenUsage (input/output).
+ */
+export declare function aggregateTokensForPlan(directory: string, sessionIds: string[]): MetricsTokenUsage;

package/dist/features/analytics/session-tracker.d.ts

@@ -0,0 +1,68 @@
+import type { TrackedSession, SessionSummary } from "./types";
+/**
+ * SessionTracker tracks tool usage and delegations across sessions,
+ * producing SessionSummary records when sessions end.
+ *
+ * Usage:
+ * - Call `startSession()` when a session begins (or lazily on first tool call)
+ * - Call `trackToolStart()` / `trackToolEnd()` on tool.execute.before/after
+ * - Call `endSession()` when the session ends → writes summary to JSONL
+ */
+export declare class SessionTracker {
+    private sessions;
+    private directory;
+    constructor(directory: string);
+    /**
+     * Start tracking a session. Idempotent — if already tracking, returns existing.
+     */
+    startSession(sessionId: string): TrackedSession;
+    /**
+     * Track a tool execution start. Lazily starts the session if needed.
+     */
+    trackToolStart(sessionId: string, toolName: string, callId: string, agent?: string): void;
+    /**
+     * Track a tool execution end. Records delegation if it was a task tool.
+     */
+    trackToolEnd(sessionId: string, toolName: string, callId: string, agent?: string): void;
+    /**
+     * Set the agent name for a session. Only sets on first call (captures primary agent).
+     */
+    setAgentName(sessionId: string, agentName: string): void;
+    /**
+     * Accumulate dollar cost from a message into the session total.
+     */
+    trackCost(sessionId: string, cost: number): void;
+    /**
+     * Track token usage from a message.updated event.
+     * Accumulates all token fields into the session's running totals.
+     * Lazily starts the session if needed.
+     */
+    trackTokenUsage(sessionId: string, tokens: {
+        input?: number;
+        output?: number;
+        reasoning?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    }): void;
+    /**
+     * End a session and persist the summary. Removes the session from tracking.
+     * Returns the generated summary, or null if the session wasn't being tracked.
+     */
+    endSession(sessionId: string): SessionSummary | null;
+    /**
+     * Check if a session is currently being tracked.
+     */
+    isTracking(sessionId: string): boolean;
+    /**
+     * Get the current tracked session data (for inspection/testing).
+     */
+    getSession(sessionId: string): TrackedSession | undefined;
+    /**
+     * Get the number of sessions currently being tracked.
+     */
+    get activeSessionCount(): number;
+}
+/**
+ * Create a new SessionTracker instance.
+ */
+export declare function createSessionTracker(directory: string): SessionTracker;