@punica/editor 1.22.9 → 1.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.22.9",
+  "version": "1.24.0",
   "description": "Punica Editor",
   "private": false,
   "type": "module",

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

@@ -192,6 +192,71 @@ declare module 'punica' {
         compactionApplied: boolean;
       }
 
+      /**
+       * The `ai.agent*` event family — a run as it happens.
+       *
+       * Every loop in the fleet publishes these, and a consumer reads a run
+       * without knowing which loop produced it. The contract, including the
+       * three obligations that are NOT payload shape (one trace per run, the
+       * loop naming itself in `origin.id`, and the MCP scope being declared),
+       * is `docs/agent-loops.md`.
+       *
+       * Correlation is on the envelope, not in the payload: `traceId` is the
+       * run — the same field the run's audited calls carry, so one query
+       * returns both halves — and `ai.agentStep` additionally carries
+       * `spanId`, the turn's own span, which is the parent of every gateway
+       * call that turn made.
+       *
+       * Declared here because they were a convention inside one file until
+       * 1.23.0: the names existed only in `kernel/ai/agentLoop.ts`, so a
+       * second loop had nothing to conform to and a consumer nothing to read
+       * against.
+       */
+      export interface AgentStartedEvent {
+        runId: string;
+        query: string;
+        /** The conversation this run continues, when it continues one. */
+        sessionId?: string;
+      }
+
+      /** One completed turn. Published after the model answers, per iteration. */
+      export interface AgentStepEvent {
+        runId: string;
+        turn: AgentTurn;
+      }
+
+      /** A tool the model asked for, published before it is dispatched. */
+      export interface AgentToolCallEvent {
+        runId: string;
+        toolCall: {
+          id: string;
+          name: string;
+          arguments: Record<string, unknown>;
+        };
+        status: 'running';
+      }
+
+      /**
+       * How that tool call settled. `status` repeats the call's own, so a
+       * consumer that missed the request event still learns the outcome —
+       * `blocked` among them, which is a refusal and not an error.
+       */
+      export interface AgentToolResultEvent {
+        runId: string;
+        toolCall: AgentToolCall;
+        status: AgentToolCall['status'];
+      }
+
+      /** Exactly one per run, whatever the outcome. */
+      export interface AgentFinishedEvent {
+        runId: string;
+        finishReason: AgentFinishReason;
+        finalText?: string;
+        usage?: AgentRunUsage;
+        /** The failure's own text, when `finishReason === 'error'`. */
+        error?: string;
+      }
+
       /**
        * Why an agent run stopped.
        *  - `final`     — the model produced a tool-call-free answer.
@@ -230,6 +295,22 @@ declare module 'punica' {
          * unpersisted, exactly as before sessions existed.
          */
         sessionId?: string;
+        /**
+         * The trace this run belongs to, when it is part of something bigger.
+         *
+         * A caller that is itself a governed call — an `ivy.agent.turn` node
+         * inside a graph run is the case this exists for — passes its own
+         * `ctx.trace` here, and the loop's model call and every tool the model
+         * then asks for are audited under that trace, one level below the
+         * caller's span. Omitted ⇒ the run is its own trace, exactly as
+         * before.
+         *
+         * Without it a turn minted a fresh trace, so the graph run and the
+         * work the model did inside it landed in the audit trail as two
+         * unrelated traces and neither an evidence package nor the run monitor
+         * could join them. Contract: `docs/agent-loops.md`.
+         */
+        trace?: { traceId: string; parentSpanId?: string };
         /**
          * Optional capability catalog filter (mirrors
          * `capability.schemaExport`'s filter shape). When omitted, the

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

@@ -293,10 +293,21 @@ declare module 'punica' {
          * own session/trace id. When `input.options.stream` is set, the
          * streaming `llm.chunk` deltas are published under this id so the
          * caller can correlate live tokens with the originating turn.
+         *
+         * `opts.trace` is the audit trail's side of the same idea and is not
+         * interchangeable with it: this call dispatches `llm.chat` back
+         * through the gateway, and without a trace to continue that inner
+         * call minted its own — so the model call an agent turn made was
+         * recorded outside the run that asked for it. Pass the caller's
+         * trace, and its own `invocationId` as `parentSpanId`, to get a
+         * parent/child pair instead.
          */
         invoke(
           input: CapabilityInput,
-          opts?: { correlationId?: string }
+          opts?: {
+            correlationId?: string;
+            trace?: { traceId: string; parentSpanId?: string };
+          }
         ): Promise<CapabilityResult>;
 
         /**

package/types/punica.module.runtime.api.d.ts

@@ -277,6 +277,71 @@ declare module 'punica' {
         bytes: Uint8Array,
         signature: PackageSignature
       ) => Promise<boolean>;
+
+      /**
+       * Install the host's span exporter for the capability pipeline. The
+       * gateway produces an OTel-shaped `CapabilitySpan` for **every** call
+       * (`traceId` / `spanId` / `parentSpanId` / duration / status /
+       * attributes) and hands it here; the substrate ships no vendor SDK, so
+       * without this the spans go to a no-op.
+       *
+       * Keep `recordSpan` non-blocking — queue and flush. It is called
+       * synchronously on the success and failure path of every capability
+       * invocation, so a slow exporter slows the whole product down.
+       *
+       * On the facade since 1.23.0. Before that it was a named module export
+       * the package entry did not re-export, which put it in the same class as
+       * `setLlmPricingTable`: documented, exported, and absent from the
+       * published bundle, so no host could reach it.
+       */
+      setCapabilityTelemetryExporter: (
+        exporter: CapabilityTelemetryExporter | undefined
+      ) => void;
+
+      /** The installed capability exporter — never undefined; a no-op by default. */
+      getCapabilityTelemetryExporter: () => CapabilityTelemetryExporter;
+
+      /**
+       * Install the host's span exporter for kernel events. Same contract as
+       * the capability exporter and the same history; `publishEvent` calls
+       * `exportSpan` for every event, so the two together are what an OTel
+       * consumer needs to read a run from outside.
+       */
+      setEventTelemetryExporter: (
+        exporter: kernel.EventTelemetryExporter | undefined
+      ) => void;
+
+      /** The installed event exporter — never undefined; a no-op by default. */
+      getEventTelemetryExporter: () => kernel.EventTelemetryExporter;
+    }
+
+    /**
+     * One completed capability call, in the OpenTelemetry span shape so a host
+     * adapter is a field rename at most. `spanId` is the call's
+     * `invocationId`, which is also what the audit record carries, so the
+     * exported span and the durable record describe the same node of the same
+     * tree.
+     */
+    export interface CapabilitySpan {
+      invocationId: string;
+      capability: string;
+      traceId: string;
+      spanId: string;
+      parentSpanId?: string;
+      startTimeMs: number;
+      durationMs: number;
+      status: 'success' | 'error';
+      errorCode?: string;
+      errorMessage?: string;
+      attributes: Record<string, string>;
+    }
+
+    /**
+     * Host contract for receiving capability spans. Implementations MUST be
+     * non-blocking; the substrate calls this from the middleware's hot path.
+     */
+    export interface CapabilityTelemetryExporter {
+      recordSpan(span: CapabilitySpan): void;
     }
 
     /**

package/types/punica.module.runtime.capabilities.d.ts

@@ -25,10 +25,18 @@ declare module 'punica' {
 
     /**
      * Origin of the capability invocation.
+     *
+     * `capability` is one capability calling another: an extension handler
+     * that delegates part of its work through the gateway, or a core provider
+     * dispatching an inner call. It was missing from the set until 1.23.0, so
+     * such a caller had to describe itself as something it was not —
+     * `ivy-node.generate` and `ivy-mcp.generate` inherited the CALLER's origin
+     * instead, which was the closest true statement available. Inheriting the
+     * caller's `trace` stays right; inheriting its origin does not.
      */
     export interface InvocationOrigin {
       /** Kind of origin */
-      kind: 'command' | 'workflow' | 'ai';
+      kind: 'command' | 'workflow' | 'ai' | 'capability';
       /** Unique identifier for the origin */
       id: string;
       /** Extension name (if applicable) */
@@ -61,6 +69,21 @@ declare module 'punica' {
     export interface InvocationContext {
       /** Session identifier */
       sessionId: string;
+      /**
+       * This call's own id, and the span id its audit record carries.
+       *
+       * **Set by the gateway**, not by the caller: anything a caller puts
+       * here is replaced, because a span id somebody else chose is a claim
+       * about the record rather than a fact of it. Present on the context a
+       * provider or an extension handler receives, absent on the one a caller
+       * builds — which is why it is optional.
+       *
+       * What it is for: a handler that re-enters the gateway passes it as
+       * `trace.parentSpanId` on the inner call, so the two calls read back as
+       * parent and child instead of as siblings. Contract:
+       * `docs/agent-loops.md`.
+       */
+      invocationId?: string;
       /**
        * Persistent AI conversation this call belongs to
        * (`kernel.AI.sessions` id). Distinct from `sessionId`, which is