@dot-ai/core 0.5.2 → 0.7.0

package/dist/extension-types.d.ts

@@ -0,0 +1,312 @@
+import type { Label, RoutingResult } from './types.js';
+/**
+ * Base context passed to every event handler (second argument).
+ * Adapters extend this with agent-specific state (providers, session control, etc.).
+ * Mirrors Pi's `ctx` pattern: handler(event, ctx).
+ */
+export interface ExtensionContext {
+    /** Current workspace root */
+    workspaceRoot: string;
+    /** Inter-extension event bus */
+    events: {
+        on(event: string, handler: (...args: unknown[]) => void): void;
+        off(event: string, handler: (...args: unknown[]) => void): void;
+        emit(event: string, ...args: unknown[]): void;
+    };
+}
+/**
+ * A section is the atomic output unit of `context_enrich`.
+ * Extensions return sections; the formatter assembles them by priority.
+ */
+export interface Section {
+    /** Unique identifier for this section (optional — anonymous sections are allowed) */
+    id?: string;
+    /** Section heading */
+    title: string;
+    /** Markdown content */
+    content: string;
+    /**
+     * Priority determines ordering and trim precedence.
+     * 100 = identity, 80 = memory, 60 = skills, 50 = tasks, 40 = tools, 30 = routing.
+     */
+    priority: number;
+    /** Which extension produced this section */
+    source: string;
+    /**
+     * How this section should be handled when the token budget is exceeded.
+     * - 'never': never trim (identity, critical context)
+     * - 'truncate': shorten content but keep section
+     * - 'drop': remove entirely (default)
+     */
+    trimStrategy?: 'never' | 'truncate' | 'drop';
+}
+/** A single resource entry discovered by an extension */
+export interface ResourceEntry {
+    /** Resource type: 'skill', 'identity', 'tool', 'prompt', etc. */
+    type: string;
+    /** Path to the resource (absolute or relative to workspace) */
+    path: string;
+    /** Labels for this specific resource */
+    labels?: string[];
+    /** Provider-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Result returned by resources_discover handlers */
+export interface ResourcesDiscoverResult {
+    /** Labels contributed to the global vocabulary */
+    labels?: string[];
+    /** Discovered resources (paths + metadata) */
+    resources?: ResourceEntry[];
+}
+/** Event for label_extract -- handlers modify and return the labels array */
+export interface LabelExtractEvent {
+    /** The user's prompt text */
+    prompt: string;
+    /** Known label vocabulary (from resources_discover) */
+    vocabulary: string[];
+    /** Current labels -- handler returns modified array */
+    labels: Label[];
+}
+/** Event for context_enrich -- replaces context_inject in v6 */
+export interface ContextEnrichEvent {
+    /** The user's prompt text */
+    prompt: string;
+    /** Matched labels for this turn */
+    labels: Label[];
+}
+/** Result from context_enrich handlers */
+export interface ContextEnrichResult {
+    /** Sections to include in the formatted context */
+    sections?: Section[];
+    /** System prompt override (for Pi-like adapters that support it) */
+    systemPrompt?: string;
+}
+/** Aggregated result from fireCollectSections */
+export interface CollectedSections {
+    sections: Section[];
+    systemPrompt: string;
+}
+/** Event for model routing */
+export interface RouteEvent {
+    /** Matched labels for this turn */
+    labels: Label[];
+}
+/** Result from route handlers — alias for RoutingResult from types.ts */
+export type RouteResult = RoutingResult;
+/** Event for input interception (Pi adapter) */
+export interface InputEvent {
+    /** Raw user input */
+    input: string;
+}
+/** Result from input handlers */
+export interface InputResult {
+    /** Transformed input (if modified) */
+    input?: string;
+    /** If true, input was consumed and should not be forwarded */
+    consumed?: boolean;
+}
+/** A parameter for a command definition */
+export interface CommandParameter {
+    /** Parameter name */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Whether this parameter is required */
+    required?: boolean;
+}
+/** Result returned by command execution */
+export interface CommandResult {
+    /** Output text to display */
+    output?: string;
+}
+/**
+ * A command definition -- aligned with Pi's /command pattern.
+ * Extensions register commands via `exports.commands`.
+ */
+export interface CommandDefinition {
+    /** Command name (without leading slash) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Parameter definitions */
+    parameters?: CommandParameter[];
+    /** Execute the command */
+    execute(args: Record<string, string>, ctx: ExtensionContext): Promise<CommandResult | void>;
+    /** Tab-completion provider */
+    completions?(prefix: string): string[] | Promise<string[]>;
+}
+/** Tool definition for extensions -- structurally compatible with Pi */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema object describing tool parameters */
+    parameters: Record<string, unknown>;
+    /** Execute the tool. ctx is optional for backward compatibility with v5 extensions. */
+    execute(input: Record<string, unknown>, ctx?: ExtensionContext): Promise<{
+        content: string;
+        details?: unknown;
+        isError?: boolean;
+    }>;
+    /** Injected into system prompt when tool is active */
+    promptSnippet?: string;
+    /** Guidelines for the LLM when using this tool */
+    promptGuidelines?: string;
+}
+/**
+ * @deprecated Use ContextEnrichEvent + ContextEnrichResult instead.
+ * Tier 1 (universal) -- context injection event.
+ */
+export interface ContextInjectEvent {
+    prompt: string;
+    labels: Label[];
+    usage?: {
+        inputTokens: number;
+        contextWindow: number;
+    };
+}
+/**
+ * @deprecated Use ContextEnrichResult instead.
+ */
+export interface ContextInjectResult {
+    inject?: string;
+}
+/**
+ * @deprecated Use ContextEnrichEvent with context_modify support.
+ * Tier 2 (rich agents only) -- message-level context modification.
+ */
+export interface ContextModifyEvent {
+    messages: Message[];
+    usage?: {
+        inputTokens: number;
+        contextWindow: number;
+    };
+}
+/**
+ * @deprecated Use ContextEnrichResult instead.
+ */
+export interface ContextModifyResult {
+    messages?: Message[];
+    inject?: string;
+}
+/** Message type for context_modify */
+export interface Message {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+/** Tool call event -- fired before tool execution */
+export interface ToolCallEvent {
+    tool: string;
+    input: Record<string, unknown>;
+}
+export interface ToolCallResult {
+    decision?: 'allow' | 'block';
+    reason?: string;
+}
+/** Tool result event -- fired after tool execution */
+export interface ToolResultEvent {
+    tool: string;
+    result: {
+        content: string;
+    };
+    isError: boolean;
+}
+/** Agent end event */
+export interface AgentEndEvent {
+    response: string;
+}
+/** Union of all extension events (v5 legacy + v6) */
+export type ExtensionEvent = {
+    type: 'resources_discover';
+} | {
+    type: 'label_extract';
+    data: LabelExtractEvent;
+} | {
+    type: 'context_enrich';
+    data: ContextEnrichEvent;
+} | {
+    type: 'route';
+    data: RouteEvent;
+} | {
+    type: 'input';
+    data: InputEvent;
+} | {
+    type: 'context_modify';
+    data: ContextModifyEvent;
+} | {
+    type: 'tool_call';
+    data: ToolCallEvent;
+} | {
+    type: 'tool_result';
+    data: ToolResultEvent;
+} | {
+    type: 'agent_start';
+} | {
+    type: 'agent_end';
+    data: AgentEndEvent;
+} | {
+    type: 'session_start';
+} | {
+    type: 'session_end';
+} | {
+    type: 'turn_start';
+} | {
+    type: 'turn_end';
+} | {
+    type: 'message_start';
+} | {
+    type: 'message_update';
+} | {
+    type: 'message_end';
+} | {
+    type: 'model_select';
+} | {
+    type: 'user_bash';
+} | {
+    type: 'session_before_switch';
+} | {
+    type: 'session_switch';
+} | {
+    type: 'session_before_compact';
+} | {
+    type: 'session_compact';
+} | {
+    type: 'context_inject';
+    data: ContextInjectEvent;
+};
+/** Extension tier metadata */
+export type ExtensionTier = 'universal' | 'rich';
+/** Event name to tier mapping */
+export declare const EVENT_TIERS: Record<string, ExtensionTier>;
+/** All valid event names */
+export type ExtensionEventName = keyof typeof EVENT_TIERS;
+/** A loaded extension with its handlers, tools, and commands */
+export interface LoadedExtension {
+    path: string;
+    handlers: Map<string, Function[]>;
+    tools: Map<string, ToolDefinition>;
+    /** Registered commands (v6) */
+    commands: Map<string, CommandDefinition>;
+    tiers: Set<ExtensionTier>;
+}
+/**
+ * Adapter capability matrix -- which events each adapter supports.
+ * v6 events listed first; legacy events marked with comments.
+ */
+export declare const ADAPTER_CAPABILITIES: Record<string, Set<string>>;
+/**
+ * Tool integration strategy per adapter.
+ * - 'native': adapter can register tools natively (Pi, OpenClaw)
+ * - 'cli': tools are exposed as CLI commands (Claude Code)
+ * - 'text': tools are described in the system prompt only (Cursor, Copilot)
+ */
+export declare const TOOL_STRATEGY: Record<string, 'native' | 'cli' | 'text'>;
+/** Extension diagnostics */
+export interface ExtensionDiagnostic {
+    path: string;
+    handlerCounts: Record<string, number>;
+    toolNames: string[];
+    /** Command names registered by this extension */
+    commandNames: string[];
+    tiers: ExtensionTier[];
+}
+//# sourceMappingURL=extension-types.d.ts.map

package/dist/extension-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-types.d.ts","sourceRoot":"","sources":["../src/extension-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMvD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,MAAM,EAAE;QACN,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;QAC/D,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;QAChE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;KAC/C,CAAC;CACH;AAQD;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,qFAAqF;IACrF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;CAC9C;AAID,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qDAAqD;AACrD,MAAM,WAAW,uBAAuB;IACtC,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;CAC7B;AAID,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,uDAAuD;IACvD,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAID,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAID,8BAA8B;AAC9B,MAAM,WAAW,UAAU;IACzB,mCAAmC;IACnC,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,yEAAyE;AACzE,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC;AAIxC,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,iCAAiC;AACjC,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAID,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC5F,8BAA8B;IAC9B,WAAW,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5D;AAID,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,uFAAuF;IACvF,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACpI,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,sCAAsC;AACtC,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,sBAAsB;AACtB,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAEtB;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAEnC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,uBAAuB,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,wBAAwB,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAE3B;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAEzD,8BAA8B;AAC9B,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,MAAM,CAAC;AAEjD,iCAAiC;AACjC,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CA4BrD,CAAC;AAEF,4BAA4B;AAC5B,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,WAAW,CAAC;AAM1D,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAClC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnC,+BAA+B;IAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACzC,KAAK,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC;CAC3B;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAuC5D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAOnE,CAAC;AAMF,4BAA4B;AAC5B,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iDAAiD;IACjD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB"}

package/dist/extension-types.js

@@ -0,0 +1,89 @@
+/** Event name to tier mapping */
+export const EVENT_TIERS = {
+    // v6 events (all universal)
+    resources_discover: 'universal',
+    label_extract: 'universal',
+    context_enrich: 'universal',
+    route: 'universal',
+    input: 'universal',
+    // Shared events
+    context_modify: 'rich',
+    tool_call: 'universal',
+    tool_result: 'rich',
+    agent_start: 'rich',
+    agent_end: 'universal',
+    session_start: 'universal',
+    session_end: 'universal',
+    turn_start: 'rich',
+    turn_end: 'rich',
+    message_start: 'rich',
+    message_update: 'rich',
+    message_end: 'rich',
+    model_select: 'rich',
+    user_bash: 'rich',
+    session_before_switch: 'rich',
+    session_switch: 'rich',
+    session_before_compact: 'rich',
+    session_compact: 'rich',
+    // v5 legacy (deprecated)
+    context_inject: 'universal',
+};
+/**
+ * Adapter capability matrix -- which events each adapter supports.
+ * v6 events listed first; legacy events marked with comments.
+ */
+export const ADAPTER_CAPABILITIES = {
+    pi: new Set([
+        'session_start', 'session_end',
+        'resources_discover',
+        'label_extract', 'context_enrich', 'context_modify', 'route',
+        'input',
+        'tool_call', 'tool_result',
+        'agent_start', 'agent_end',
+        'turn_start', 'turn_end',
+        'message_start', 'message_update', 'message_end',
+        'session_before_switch', 'session_switch',
+        'session_before_compact', 'session_compact',
+        'model_select', 'user_bash',
+        // Legacy (deprecated)
+        'context_inject',
+    ]),
+    'claude-code': new Set([
+        'session_start', 'session_end',
+        'resources_discover',
+        'label_extract', 'context_enrich', 'route',
+        'tool_call', 'tool_result',
+        'agent_end',
+        // Legacy (deprecated)
+        'context_inject',
+    ]),
+    openclaw: new Set([
+        'session_start', 'session_end',
+        'resources_discover',
+        'label_extract', 'context_enrich', 'route',
+        'agent_end',
+        // Legacy (deprecated)
+        'context_inject',
+    ]),
+    sync: new Set([
+        'resources_discover',
+        'context_enrich', 'route',
+        // Legacy (deprecated)
+        'context_inject',
+    ]),
+};
+/**
+ * Tool integration strategy per adapter.
+ * - 'native': adapter can register tools natively (Pi, OpenClaw)
+ * - 'cli': tools are exposed as CLI commands (Claude Code)
+ * - 'text': tools are described in the system prompt only (Cursor, Copilot)
+ */
+export const TOOL_STRATEGY = {
+    pi: 'native',
+    openclaw: 'native',
+    'claude-code': 'cli',
+    sync: 'text',
+    cursor: 'text',
+    copilot: 'text',
+};
+//# sourceMappingURL=extension-types.js.map

package/dist/extension-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-types.js","sourceRoot":"","sources":["../src/extension-types.ts"],"names":[],"mappings":"AAuSA,iCAAiC;AACjC,MAAM,CAAC,MAAM,WAAW,GAAkC;IACxD,4BAA4B;IAC5B,kBAAkB,EAAE,WAAW;IAC/B,aAAa,EAAE,WAAW;IAC1B,cAAc,EAAE,WAAW;IAC3B,KAAK,EAAE,WAAW;IAClB,KAAK,EAAE,WAAW;IAClB,gBAAgB;IAChB,cAAc,EAAE,MAAM;IACtB,SAAS,EAAE,WAAW;IACtB,WAAW,EAAE,MAAM;IACnB,WAAW,EAAE,MAAM;IACnB,SAAS,EAAE,WAAW;IACtB,aAAa,EAAE,WAAW;IAC1B,WAAW,EAAE,WAAW;IACxB,UAAU,EAAE,MAAM;IAClB,QAAQ,EAAE,MAAM;IAChB,aAAa,EAAE,MAAM;IACrB,cAAc,EAAE,MAAM;IACtB,WAAW,EAAE,MAAM;IACnB,YAAY,EAAE,MAAM;IACpB,SAAS,EAAE,MAAM;IACjB,qBAAqB,EAAE,MAAM;IAC7B,cAAc,EAAE,MAAM;IACtB,sBAAsB,EAAE,MAAM;IAC9B,eAAe,EAAE,MAAM;IACvB,yBAAyB;IACzB,cAAc,EAAE,WAAW;CAC5B,CAAC;AAmBF;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAgC;IAC/D,EAAE,EAAE,IAAI,GAAG,CAAC;QACV,eAAe,EAAE,aAAa;QAC9B,oBAAoB;QACpB,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,OAAO;QAC5D,OAAO;QACP,WAAW,EAAE,aAAa;QAC1B,aAAa,EAAE,WAAW;QAC1B,YAAY,EAAE,UAAU;QACxB,eAAe,EAAE,gBAAgB,EAAE,aAAa;QAChD,uBAAuB,EAAE,gBAAgB;QACzC,wBAAwB,EAAE,iBAAiB;QAC3C,cAAc,EAAE,WAAW;QAC3B,sBAAsB;QACtB,gBAAgB;KACjB,CAAC;IACF,aAAa,EAAE,IAAI,GAAG,CAAC;QACrB,eAAe,EAAE,aAAa;QAC9B,oBAAoB;QACpB,eAAe,EAAE,gBAAgB,EAAE,OAAO;QAC1C,WAAW,EAAE,aAAa;QAC1B,WAAW;QACX,sBAAsB;QACtB,gBAAgB;KACjB,CAAC;IACF,QAAQ,EAAE,IAAI,GAAG,CAAC;QAChB,eAAe,EAAE,aAAa;QAC9B,oBAAoB;QACpB,eAAe,EAAE,gBAAgB,EAAE,OAAO;QAC1C,WAAW;QACX,sBAAsB;QACtB,gBAAgB;KACjB,CAAC;IACF,IAAI,EAAE,IAAI,GAAG,CAAC;QACZ,oBAAoB;QACpB,gBAAgB,EAAE,OAAO;QACzB,sBAAsB;QACtB,gBAAgB;KACjB,CAAC;CACH,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAA8C;IACtE,EAAE,EAAE,QAAQ;IACZ,QAAQ,EAAE,QAAQ;IAClB,aAAa,EAAE,KAAK;IACpB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,MAAM;IACd,OAAO,EAAE,MAAM;CAChB,CAAC"}

package/dist/format.d.ts

@@ -1,5 +1,6 @@
-import type { EnrichedContext } from './types.js';
+import type { EnrichedContext, BudgetWarning } from './types.js';
 import type { Logger } from './logger.js';
+import type { Capability } from './capabilities.js';
 export interface FormatOptions {
     /** Skip identity sections (useful when already injected at session start) */
     skipIdentities?: boolean;
@@ -7,12 +8,23 @@ export interface FormatOptions {
     maxSkillLength?: number;
     /** Max number of skills to include (already sorted by match relevance). Default: unlimited */
     maxSkills?: number;
+    /** Max estimated tokens (chars / 4). When exceeded, content is trimmed. Default: no limit */
+    tokenBudget?: number;
+    /** Called when budget was exceeded and trimming occurred. Diagnostic signal. */
+    onBudgetExceeded?: (warning: BudgetWarning) => void;
     /** Optional logger for tracing */
     logger?: Logger;
+    /** Skill disclosure mode. 'progressive' shows name+description only, 'full' shows entire content */
+    skillDisclosure?: 'full' | 'progressive';
 }
 /**
  * Format an EnrichedContext into markdown sections for injection into agent context.
  * Sections are ordered by priority: identity > memory > skills > tools > routing.
  */
 export declare function formatContext(ctx: EnrichedContext, options?: FormatOptions): string;
+/**
+ * Format tool hints from capabilities that have promptSnippet or promptGuidelines.
+ * Returns empty string if no capabilities have hints.
+ */
+export declare function formatToolHints(capabilities: Capability[]): string;
 //# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA2C,MAAM,YAAY,CAAC;AAC3F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oGAAoG;IACpG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAyDnF"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAiD,aAAa,EAAE,MAAM,YAAY,CAAC;AAChH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oGAAoG;IACpG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;IACpD,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,eAAe,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CA6InF;AAkDD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,UAAU,EAAE,GAAG,MAAM,CAYlE"}

package/dist/format.js

@@ -5,35 +5,117 @@
 export function formatContext(ctx, options) {
     const start = performance.now();
     const sections = [];
-    // Identity sections (sorted by priority, highest first)
+    // Identity sections (sorted by priority DESC, then by type alphabetically for stability)
     if (!options?.skipIdentities) {
-        const sortedIdentities = [...ctx.identities].sort((a, b) => b.priority - a.priority);
+        const sortedIdentities = [...ctx.identities].sort((a, b) => {
+            if (b.priority !== a.priority)
+                return b.priority - a.priority;
+            return a.type.localeCompare(b.type);
+        });
         for (const identity of sortedIdentities) {
             if (identity.content) {
                 sections.push(identity.content);
             }
         }
     }
-    // Memory section
-    if (ctx.memories.length > 0) {
-        sections.push(formatMemory(ctx.memories));
+    // Memory section (sorted by date DESC for stability)
+    const sortedMemories = [...ctx.memories].sort((a, b) => {
+        if (!a.date && !b.date)
+            return 0;
+        if (!a.date)
+            return 1;
+        if (!b.date)
+            return -1;
+        return b.date.localeCompare(a.date);
+    });
+    if (sortedMemories.length > 0 || ctx.memoryDescription) {
+        sections.push(formatMemory(sortedMemories, ctx.memoryDescription));
+    }
+    // Recent tasks section
+    if (ctx.recentTasks && ctx.recentTasks.length > 0) {
+        sections.push(formatTasks(ctx.recentTasks));
     }
-    // Skills section
-    let loadedSkills = ctx.skills.filter(s => s.content);
+    // Skills section (sorted by name alphabetically for determinism)
+    let loadedSkills = [...ctx.skills].sort((a, b) => a.name.localeCompare(b.name)).filter(s => s.content);
     if (options?.maxSkills != null) {
         loadedSkills = loadedSkills.slice(0, options.maxSkills);
     }
     if (loadedSkills.length > 0) {
-        sections.push(formatSkills(loadedSkills, options?.maxSkillLength));
+        sections.push(formatSkills(loadedSkills, options?.maxSkillLength, options?.skillDisclosure));
     }
-    // Tools section
-    if (ctx.tools.length > 0) {
-        sections.push(formatTools(ctx.tools));
+    // Tools section (sorted by name alphabetically for determinism)
+    const sortedTools = [...ctx.tools].sort((a, b) => a.name.localeCompare(b.name));
+    if (sortedTools.length > 0) {
+        sections.push(formatTools(sortedTools));
     }
     // Routing hint
     if (ctx.routing.model !== 'default') {
         sections.push(formatRouting(ctx.routing));
     }
+    // Budget enforcement — trim if over token budget
+    if (options?.tokenBudget != null) {
+        const estimate = () => Math.round(sections.join('\n\n---\n\n').length / 4);
+        let current = estimate();
+        if (current > options.tokenBudget) {
+            const actions = [];
+            const skillSectionIdx = sections.findIndex(s => s.startsWith('## Active Skills'));
+            const memorySectionIdx = sections.findIndex(s => s.startsWith('## Relevant Memory'));
+            // Strategy 1: Truncate skill content to 2000 chars
+            if (current > options.tokenBudget && skillSectionIdx !== -1 && options?.maxSkillLength == null) {
+                const longSkills = loadedSkills.filter(s => (s.content?.length ?? 0) > 2000).length;
+                if (longSkills > 0) {
+                    sections[skillSectionIdx] = formatSkills(loadedSkills, 2000, options?.skillDisclosure);
+                    actions.push(`truncated ${longSkills} skills to 2000 chars`);
+                    current = estimate();
+                }
+            }
+            // Strategy 2: Drop oldest memories (keep most recent 5)
+            if (current > options.tokenBudget && memorySectionIdx !== -1 && sortedMemories.length > 5) {
+                const kept = sortedMemories.slice(0, 5);
+                const dropped = sortedMemories.length - 5;
+                sections[memorySectionIdx] = formatMemory(kept, ctx.memoryDescription);
+                actions.push(`dropped ${dropped} oldest memories`);
+                current = estimate();
+            }
+            // Strategy 3: Drop skills by reverse order
+            if (current > options.tokenBudget && skillSectionIdx !== -1 && loadedSkills.length > 1) {
+                while (loadedSkills.length > 1 && current > options.tokenBudget) {
+                    const dropped = loadedSkills.pop();
+                    actions.push(`dropped skill: ${dropped.name}`);
+                    sections[skillSectionIdx] = formatSkills(loadedSkills, options?.maxSkillLength ?? 2000, options?.skillDisclosure);
+                    current = estimate();
+                }
+            }
+            if (actions.length > 0) {
+                const warning = { budget: options.tokenBudget, actual: current, actions };
+                options.onBudgetExceeded?.(warning);
+                options?.logger?.log({
+                    timestamp: new Date().toISOString(),
+                    level: current > options.tokenBudget ? 'warn' : 'info',
+                    phase: 'format',
+                    event: 'budget_trimmed',
+                    data: warning,
+                    durationMs: Math.round(performance.now() - start),
+                });
+            }
+            else if (current > options.tokenBudget) {
+                const warning = {
+                    budget: options.tokenBudget,
+                    actual: current,
+                    actions: ['budget exceeded by non-trimmable content (identities)'],
+                };
+                options.onBudgetExceeded?.(warning);
+                options?.logger?.log({
+                    timestamp: new Date().toISOString(),
+                    level: 'warn',
+                    phase: 'format',
+                    event: 'budget_exceeded_no_action',
+                    data: warning,
+                    durationMs: Math.round(performance.now() - start),
+                });
+            }
+        }
+    }
     const result = sections.join('\n\n---\n\n');
     options?.logger?.log({
         timestamp: new Date().toISOString(),
@@ -52,19 +134,34 @@ export function formatContext(ctx, options) {
     });
     return result;
 }
-function formatMemory(memories) {
+function formatMemory(memories, description) {
     const lines = ['## Relevant Memory\n'];
-    for (const m of memories.slice(0, 10)) { // Limit to 10 most relevant
+    if (description) {
+        lines.push(`> ${description}\n`);
+    }
+    for (const m of memories.slice(0, 10)) {
         const date = m.date ? ` (${m.date})` : '';
         lines.push(`- ${m.content}${date}`);
     }
     return lines.join('\n');
 }
-function formatSkills(skills, maxLength) {
+function formatTasks(tasks) {
+    const lines = ['## Current Tasks (In Progress)\n'];
+    for (const t of tasks.slice(0, 10)) {
+        const project = t.project ? ` [${t.project}]` : '';
+        const priority = t.priority ? ` (${t.priority})` : '';
+        lines.push(`- ${t.text}${project}${priority}`);
+    }
+    return lines.join('\n');
+}
+function formatSkills(skills, maxLength, disclosure) {
     const lines = ['## Active Skills\n'];
     for (const s of skills) {
         lines.push(`### ${s.name}`);
-        if (s.content) {
+        if (disclosure === 'progressive') {
+            lines.push(s.description);
+        }
+        else if (s.content) {
             if (maxLength != null && s.content.length > maxLength) {
                 lines.push(s.content.slice(0, maxLength) + '\n\n[...truncated]');
             }
@@ -83,6 +180,25 @@ function formatTools(tools) {
     }
     return lines.join('\n');
 }
+/**
+ * Format tool hints from capabilities that have promptSnippet or promptGuidelines.
+ * Returns empty string if no capabilities have hints.
+ */
+export function formatToolHints(capabilities) {
+    const withHints = capabilities.filter(c => c.promptSnippet || c.promptGuidelines);
+    if (withHints.length === 0)
+        return '';
+    const lines = ['## Tool Hints\n'];
+    for (const cap of withHints) {
+        lines.push(`### ${cap.name}`);
+        if (cap.promptSnippet)
+            lines.push(cap.promptSnippet);
+        if (cap.promptGuidelines)
+            lines.push(`\n> ${cap.promptGuidelines}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
 function formatRouting(routing) {
     return `## Model Routing\n\nRecommended model: **${routing.model}** (${routing.reason})`;
 }