@punica/editor 1.0.6 → 1.0.7

package/types/punica.module.kernel.ai.d.ts

@@ -0,0 +1,462 @@
+declare module 'punica' {
+  export namespace kernel {
+    export namespace AI {
+      export type StepStatus =
+        | 'pending'
+        | 'running'
+        | 'blocked'
+        | 'success'
+        | 'failed'
+        | 'cancelled';
+
+      export interface AiPlanStep {
+        stepId: string;
+        capabilityId: string;
+        input?: unknown;
+      }
+
+      export interface AiPlan {
+        planId: string;
+        query: string;
+        steps: AiPlanStep[];
+        createdAtMs: number;
+      }
+
+      export interface AiRunStep extends AiPlanStep {
+        status: StepStatus;
+        startedAtMs?: number;
+        finishedAtMs?: number;
+        correlationId?: string;
+        resultPayload?: unknown;
+        error?: string;
+      }
+
+      export interface AiRun {
+        runId: string;
+        planId: string;
+        startedAtMs: number;
+        finishedAtMs?: number;
+        steps: AiRunStep[];
+      }
+
+      export interface PendingApproval {
+        pendingId: string;
+        kind: string;
+        id: string;
+        risk: string;
+        approval: string;
+        reason?: string;
+        correlationId?: string;
+        /**
+         * Trace id of the invocation that hit the gate (an agent run id
+         * for agent-loop calls). Lets approval waiters and per-session UI
+         * match a pending to ITS run when concurrent runs gate the same
+         * capability.
+         */
+        traceId?: string;
+        workspaceId?: string;
+        timestampMs: number;
+      }
+
+      /**
+       * Why an agent tool call settled the way it did.
+       *  - `success` — the gateway returned a result.
+       *  - `failed`  — the gateway threw (validation, provider error, …).
+       *  - `blocked` — the call was policy-gated and never approved
+       *    (dismissed, timed out, or the run was cancelled while waiting).
+       */
+      export type AgentToolCallStatus = 'success' | 'failed' | 'blocked';
+
+      /**
+       * One capability invocation the model decided to make during an
+       * agent turn, paired with how it resolved after dispatch through
+       * the gateway.
+       */
+      export interface AgentToolCall {
+        /** Provider-supplied call id; correlates the result back to the call. */
+        id: string;
+        /** Capability id the model invoked (matches a tool catalog entry). */
+        name: string;
+        /**
+         * Arguments the call was finally dispatched with. When `repaired`
+         * is true these are the corrected arguments, not the model's
+         * original (schema-invalid) ones.
+         */
+        arguments: Record<string, unknown>;
+        status: AgentToolCallStatus;
+        /** Gateway result when `status === 'success'`. */
+        resultPayload?: unknown;
+        /** Error message when `status === 'failed'` / `'blocked'`. */
+        error?: string;
+        /**
+         * True when the model's original arguments failed input-schema
+         * validation and were repaired (re-asked against the schema) before
+         * a successful dispatch. Surfaced so the UI can mark the call as
+         * auto-corrected.
+         */
+        repaired?: boolean;
+      }
+
+      /**
+       * A single iteration of the agent loop: the model's response for
+       * this turn plus any tool calls it made (resolved). A turn with no
+       * tool calls and assistant text is the final answer.
+       */
+      export interface AgentTurn {
+        /** Zero-based turn index within the run. */
+        index: number;
+        /** Plain-text the model produced this turn (final answer or narration). */
+        assistantText?: string;
+        /** Reasoning trace, when the provider exposes a thinking channel. */
+        thinking?: string;
+        toolCalls: AgentToolCall[];
+        /**
+         * Token usage of this turn's LLM call, when the provider/stream
+         * surfaces it. Absent for providers that don't report usage
+         * (e.g. the Anthropic/OpenAI stream path before a host adapter).
+         */
+        usage?: runtime.LlmUsage;
+        /** Wall-clock duration of this turn's LLM call, in milliseconds. */
+        latencyMs?: number;
+      }
+
+      /**
+       * Aggregated accountability roll-up for a whole agent run. Summed
+       * from each turn's `usage` plus the run's wall-clock duration.
+       * Token fields are always present (zero when no provider reported
+       * usage); `totalCost` only when a host pricing table fed `meta`.
+       */
+      export interface AgentRunUsage {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        /**
+         * Cache-read subset of `inputTokens` across the run (vendor prompt
+         * caching). Present only when at least one turn reported cache
+         * activity — absence means the provider surfaced no cache signal,
+         * not that caching was cold.
+         */
+        cacheReadTokens?: number;
+        /** Total cost in USD; present only when call meta carried it. */
+        totalCost?: number;
+        /** Wall-clock duration of the whole run, in milliseconds. */
+        latencyMs: number;
+        /** Number of turns (LLM calls) the run took. */
+        steps: number;
+        /** Total tool dispatches across the run. */
+        toolCalls: number;
+      }
+
+      /**
+       * Per-turn token telemetry published as `ai.agentTurnUsage` after each
+       * LLM call inside an agent run. `est*` fields are substrate-side
+       * estimates (chars/4 heuristic unless a host injected a real
+       * tokenizer); `reported*` fields echo what the provider surfaced.
+       * Feeds token-efficiency dashboards: tool-def overhead per turn,
+       * history growth, and cache hit rate are all derivable from the
+       * event stream without provider cooperation.
+       */
+      export interface AgentTurnUsageEvent {
+        runId: string;
+        /** Zero-based turn index within the run. */
+        step: number;
+        /** Estimated tokens spent on the `tools` array this turn. */
+        estToolDefTokens: number;
+        /** Estimated tokens spent on the message history this turn. */
+        estHistoryTokens: number;
+        /** Estimated tokens of the system prompt. */
+        estSystemTokens: number;
+        reportedInputTokens?: number;
+        reportedOutputTokens?: number;
+        /** Vendor cache-read tokens for this turn, when reported. */
+        cacheReadTokens?: number;
+        /** Number of full tool definitions sent this turn. */
+        toolCount: number;
+        /** Number of catalog entries deferred (index-only, not full schema). */
+        deferredToolCount: number;
+        /** True when history compaction ran before this turn's LLM call. */
+        compactionApplied: boolean;
+      }
+
+      /**
+       * Why an agent run stopped.
+       *  - `final`     — the model produced a tool-call-free answer.
+       *  - `maxSteps`  — the step budget was exhausted first.
+       *  - `cancelled` — the user requested cancellation (`ai.cancelRun`).
+       *  - `blocked`   — a policy-gated tool was not approved.
+       *  - `error`     — the loop hit an unrecoverable error (e.g. no LLM).
+       */
+      export type AgentFinishReason =
+        | 'final'
+        | 'maxSteps'
+        | 'cancelled'
+        | 'blocked'
+        | 'error';
+
+      /**
+       * Input to a single agent run. The catalog the model may call is
+       * narrowed by `toolFilter` (Faz 2 ships a curated subset; the full
+       * registry comes in Faz 3).
+       */
+      export interface AgentRunInput {
+        query: string;
+        /**
+         * Persistent conversation to continue (`kernel.AI.sessions` id).
+         * When set, the run seeds its message history from the session's
+         * context view (warm continuation) and appends its turns back to
+         * the session on finish — every finish reason, so partial context
+         * survives cancel/maxSteps. Omitted ⇒ the run is cold and
+         * unpersisted, exactly as before sessions existed.
+         */
+        sessionId?: string;
+        /**
+         * Optional capability catalog filter (mirrors
+         * `capability.schemaExport`'s filter shape). When omitted, the
+         * loop applies its built-in curated default.
+         */
+        toolFilter?: Record<string, unknown>;
+        /** Maximum loop iterations before stopping with `maxSteps`. */
+        maxSteps?: number;
+        /**
+         * Quality/cost profile for the run. Providers may route models
+         * on it, and it selects the run's context budget (how much
+         * history is kept verbatim vs compacted, tool-result caps).
+         * Default: 'balanced'.
+         */
+        profile?: runtime.LlmProfile;
+        /** Optional instruction-class id to source the system prompt from. */
+        instructionClass?: string;
+        /**
+         * Include `ivy-node`-origin capabilities (the generated `ivy.node.*`
+         * sample nodes) in the curated default catalog. Off by default — these
+         * are workflow building blocks, not general IDE actions, so a normal
+         * assistant query never sees them. Set `true` on the ivy-* generation
+         * path that wants the model to compose existing nodes. Ignored when an
+         * explicit `toolFilter` is supplied (that selection is verbatim).
+         */
+        includeIvyNodes?: boolean;
+        /**
+         * Include `mcp`-origin capabilities (external MCP server tools) in the
+         * curated default catalog. Off by default — external MCP servers are
+         * third-party integrations rooted outside the workspace (a filesystem
+         * server rooted elsewhere, a GitHub commit surface, …); the autonomous
+         * agent reaching for them unprompted routes work outside the project
+         * (e.g. writing a file's content to an external target, leaving the
+         * workspace file empty). The product opts in per invocation when the
+         * user actually wants the agent to use MCP tools. Mirrors
+         * `includeIvyNodes` — a generic origin gate, not a per-server rule.
+         * Ignored when an explicit `toolFilter` is supplied (verbatim).
+         */
+        includeMcp?: boolean;
+        /**
+         * Per-server MCP opt-in: the `mcp.<server>.*` server ids the agent may
+         * use (e.g. `['github', 'filesystem']`). An mcp-origin tool is included
+         * only when its server id is listed here (or `includeMcp` is true, the
+         * coarse allow-all). Empty/omitted ⇒ no MCP tools (workspace-scoped
+         * default). Lets the product surface a per-server picker instead of an
+         * all-or-nothing toggle. Ignored when an explicit `toolFilter` is
+         * supplied (verbatim).
+         */
+        allowedMcpServers?: string[];
+        /**
+         * Deferred tool loading (tiered catalog). On by default for large
+         * curated catalogs: the model receives a small hot set of full
+         * tool definitions plus a one-line index of the rest, and loads
+         * full schemas on demand via `capability.search` /
+         * `capability.describe`. Set `false` to send the legacy flat
+         * narrowed catalog instead. Ignored when `toolFilter` is
+         * supplied (verbatim selection is always fully loaded).
+         */
+        deferToolLoading?: boolean;
+        /**
+         * Size of the fully-loaded hot set when deferred loading is
+         * active (meta-tools not counted). Default ~16.
+         */
+        hotSetSize?: number;
+      }
+
+      /** Terminal result of an agent run. */
+      export interface AgentRunResult {
+        runId: string;
+        finishReason: AgentFinishReason;
+        steps: AgentTurn[];
+        /** The model's final answer text, when `finishReason === 'final'`. */
+        finalText?: string;
+        /** Aggregated token/cost/latency roll-up for the run. */
+        usage?: AgentRunUsage;
+      }
+
+      /**
+       * Metadata for one persistent AI conversation session. Small enough to
+       * live in the session index blob — the transcript itself is stored per
+       * session and loaded lazily.
+       */
+      export interface AiSessionMeta {
+        sessionId: string;
+        workspaceId?: string;
+        /**
+         * Display title. Auto-generated from the first user message
+         * (trimmed ~48 chars) until the user renames it.
+         */
+        title: string;
+        createdAtMs: number;
+        updatedAtMs: number;
+        archived?: boolean;
+        /** Transcript length (messages), maintained on append. */
+        messageCount: number;
+        /** The agent run that last touched this session. */
+        lastRunId?: string;
+        /** Informational: model/mode used on the last run. */
+        modelId?: string;
+        agentMode?: boolean;
+        policyMode?: 'suggest' | 'execute';
+        /**
+         * Rough running token estimate of the transcript (chars/4). Input to
+         * compaction triggers — not a billing figure.
+         */
+        tokenEstimate?: number;
+        /** Cumulative run consumption; absent until the first recorded run. */
+        usage?: AiSessionUsage;
+      }
+
+      /**
+       * Cumulative provider-reported consumption for one session, summed
+       * from each agent run's `AgentRunUsage` roll-up on finish. Unlike
+       * `tokenEstimate` (transcript-size heuristic), these are billing-grade
+       * figures. `totalCostUsd` is present only once a run carried host
+       * pricing, and is a lower bound when some runs lacked it.
+       */
+      export interface AiSessionUsage {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheReadTokens: number;
+        totalCostUsd?: number;
+        /** Number of agent runs accumulated into this session. */
+        runCount: number;
+        lastRunAtMs?: number;
+      }
+
+      /**
+       * One transcript message. A superset of `runtime.LlmMessage` so the
+       * stored history can be replayed into an LLM request directly.
+       */
+      export interface AiSessionMessage {
+        id: string;
+        role: 'system' | 'user' | 'assistant' | 'tool';
+        content: string;
+        toolCalls?: Array<{
+          id: string;
+          name: string;
+          arguments: Record<string, unknown>;
+        }>;
+        toolCallId?: string;
+        name?: string;
+        createdAtMs: number;
+        /** The agent run that produced this message, when applicable. */
+        runId?: string;
+      }
+
+      /**
+       * The compact replay set actually fed to the LLM when a run continues
+       * this session — the compaction hook. The full `transcript` stays
+       * intact for UI restore; `contextView` holds the token-bounded view
+       * (summary + recent tail). Absent contextView ⇒ consumers derive a
+       * tail-of-transcript view.
+       */
+      export interface AiSessionContextView {
+        messages: AiSessionMessage[];
+        /** Prepended as a system message when present. */
+        summaryText?: string;
+        /** Transcript watermark: messages up to this id are summarized. */
+        compactedUpToMessageId?: string;
+        updatedAtMs: number;
+      }
+
+      /** Full stored record for one session. */
+      export interface AiSessionRecord {
+        version: 1;
+        meta: AiSessionMeta;
+        transcript: AiSessionMessage[];
+        contextView?: AiSessionContextView;
+      }
+
+      /**
+       * Pluggable compaction strategy (token-efficiency workstream plugs in
+       * via `AiSessionsApi.setCompactor`). The substrate default keeps a
+       * plain tail-of-transcript context view.
+       */
+      export interface AiSessionCompactor {
+        shouldCompact(record: AiSessionRecord): boolean;
+        compact(record: AiSessionRecord): Promise<AiSessionContextView>;
+      }
+
+      /**
+       * Substrate-central AI session service (`punica.kernel.AI.sessions`).
+       * Persistent, workspace-scoped conversation sessions: the assistant UI
+       * lists/switches them, and `ai.agent.run` continues one when given a
+       * `sessionId`. Storage is host-injectable (approvalStore pattern);
+       * default persists to localStorage.
+       */
+      export interface AiSessionsApi {
+        create(input?: { workspaceId?: string; title?: string }): AiSessionMeta;
+        /** Sorted by updatedAtMs desc. Filtered to a workspace when given. */
+        list(workspaceId?: string): AiSessionMeta[];
+        get(sessionId: string): AiSessionRecord | null;
+        rename(sessionId: string, title: string): boolean;
+        archive(sessionId: string, archived?: boolean): boolean;
+        delete(sessionId: string): boolean;
+        /**
+         * Append messages to the transcript (and bump meta). Content is
+         * size-capped; the transcript is bounded (oldest messages fall out
+         * past the cap). Fires the compactor when its trigger reports due.
+         */
+        appendMessages(
+          sessionId: string,
+          messages: AiSessionMessage[],
+          opts?: { runId?: string }
+        ): void;
+        /**
+         * The replay set for continuing this session in an LLM request:
+         * `contextView` when present, otherwise a tail of the transcript
+         * (trimmed so it never starts mid tool-call exchange).
+         */
+        getContextMessages(sessionId: string): runtime.LlmMessage[];
+        setCompactor(compactor: AiSessionCompactor | undefined): void;
+        /**
+         * Accumulate one run's usage roll-up into `meta.usage` and publish
+         * `ai.sessionUpdated` (payload flag `usageRecorded: true`).
+         * Returns false when the session does not exist.
+         */
+        recordUsage(sessionId: string, usage: AgentRunUsage): boolean;
+      }
+
+      export const sessions: AiSessionsApi;
+
+      export interface AiApi {
+        initialize(): void;
+        /**
+         * Execute the last suggested plan. Pass `editedPlan` to run a
+         * user-edited copy instead (plan-before-act editing): it replaces the
+         * held plan before running. Omit to run the last plan as-is.
+         */
+        runLastPlan(editedPlan?: AiPlan): Promise<AiRun>;
+        getLastPlan(): AiPlan | null;
+        getPendingApprovals(): PendingApproval[];
+        approvePending(pendingId: string, scope: kernel.ApprovalScope): boolean;
+        dismissPending(pendingId: string): boolean;
+        /**
+         * Run the agentic tool-use loop: the model repeatedly decides on
+         * capabilities to call as tools, the loop dispatches them through
+         * the gateway (policy/approval/audit), feeds results back, and
+         * continues until a final answer, the step budget, cancellation,
+         * or an unapproved gate. Each iteration publishes `ai.agent*`
+         * events for live rendering.
+         */
+        runAgent(input: AgentRunInput): Promise<AgentRunResult>;
+      }
+
+      export const manager: AiApi;
+    }
+  }
+}

package/types/punica.module.kernel.commands.d.ts

@@ -0,0 +1,49 @@
+declare module 'punica' {
+  export namespace kernel {
+    export namespace Commands {
+      interface IDisposable {
+        dispose(): void;
+      }
+
+      interface ICommand {
+        title: string;
+        /**
+         * Optional category (group label) for use in command palette or menus.
+         */
+        category?: string;
+        /**
+         * Optional human-readable description for use in command palette.
+         */
+        description?: string;
+        /**
+         * Optional list of keywords/aliases to improve searchability.
+         */
+        keywords?: string[];
+        /**
+         * Optional context expression controlling when the command is visible.
+         * Syntax is implementation-defined (e.g. "editorLang == 'python'").
+         */
+        when?: string;
+        disposable?: Disposable;
+        execute(...args: any[]): any;
+      }
+
+      interface ICommandManager {
+        registerCommand(commandName: string, command: ICommand): void;
+        /**
+         * Execute a command and return its result. Commands may return a value or a Promise.
+         * Callers can `await` this for async commands.
+         */
+        executeCommand(commandName: string, ...args: any[]): any;
+        disposeCommand(commandName: string): void;
+        /**
+         * Returns a snapshot of all registered commands and their metadata.
+         * This is primarily intended for use by tools like the command palette.
+         */
+        getAllCommands?(): { id: string; command: ICommand }[];
+      }
+
+      const manager: ICommandManager;
+    }
+  }
+}