@punica/editor 1.39.1 → 1.41.1

package/package.json

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

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

@@ -60,6 +60,12 @@ declare module 'punica' {
          * to a name, not to an action.
          */
         argsPreview?: unknown;
+        /**
+         * The widest grant the rule in force accepts
+         * (`kernel.PolicyRequest.maxScope`). A card offers no wider
+         * choice, and `approvePending` clamps a wider one to it.
+         */
+        maxScope?: ApprovalScope;
         correlationId?: string;
         /**
          * Trace id of the invocation that hit the gate (an agent run id
@@ -86,6 +92,29 @@ declare module 'punica' {
        * agent turn, paired with how it resolved after dispatch through
        * the gateway.
        */
+      /**
+       * A person's verdict on a cell an agent wrote, as
+       * `extension-ipynb-viewer` publishes it: `ai.cellKept`,
+       * `ai.cellRejected`, `ai.cellRestored`, each `kind: 'audit'` under the
+       * trace of the call that made the cell. The kernel relays a rejection
+       * or a restore to the AI session named on the record as one user-role
+       * note (`name: 'notebook'`), so the loop's next run in that
+       * conversation knows. Contract: `docs/cell-provenance.md`.
+       */
+      export interface CellReviewPayload {
+        path: string;
+        cellId: string;
+        kind: 'insert' | 'replace';
+        /** `origin.id` of the call that wrote the cell. */
+        originId: string;
+        runId: string;
+        traceId: string;
+        /** The conversation the call came from; absent means nobody is told. */
+        sessionId?: string;
+        /** Where the cell sat, 0-based. */
+        index: number;
+      }
+
       export interface AgentToolCall {
         /** Provider-supplied call id; correlates the result back to the call. */
         id: string;
@@ -109,6 +138,21 @@ declare module 'punica' {
          * auto-corrected.
          */
         repaired?: boolean;
+        /**
+         * True when a person edited the arguments on the approval card
+         * before the call ran (`ai.editPendingArguments`). `arguments` are
+         * then the person's, merged over the model's raw call by the rule
+         * in `approvalManagement.ts`, and the model is told so in the tool
+         * result it reads next.
+         */
+        edited?: boolean;
+        /**
+         * With `edited`: the fields the person changed, as they typed them
+         * over the redacted preview. A field they removed is absent. Never
+         * the merged raw call, so a masked value they left alone stays out
+         * of every transcript this reaches.
+         */
+        editedFields?: Record<string, unknown>;
       }
 
       /**
@@ -143,8 +187,13 @@ declare module 'punica' {
          * reader a tree of ghosts. So a failed turn is a node that says
          * what happened to it rather than a node that is missing.
          */
-        outcome?: 'error' | 'cancelled';
-        /** The failure text, when `outcome` is `'error'`. */
+        /**
+         * `blocked` when the turn's own model call was refused by a rule or
+         * held for a person nobody answered (1.41.0): a refusal is not an
+         * error, and the run then finishes `blocked`.
+         */
+        outcome?: 'error' | 'cancelled' | 'blocked';
+        /** The failure text, when `outcome` is `'error'` or `'blocked'`. */
         error?: string;
       }
 
@@ -286,6 +335,21 @@ declare module 'punica' {
         | 'blocked'
         | 'error';
 
+      /**
+       * How free one run is, chosen per run by the person who starts it.
+       *
+       * The stance acts on exactly one rule of the gate — the agent-mode
+       * profile that holds an AI actor's writes and high-risk calls for a
+       * person (`docs/approvals.md`) — and on nothing in
+       * `.punica/policy.yaml`, whose `deny` and `require` hold in every
+       * stance. `ask` offers the model no tools at all; `observe` refuses
+       * what the profile would have held, since a run that only looks has
+       * nobody to ask; `assist` is the profile as it stands, and what an
+       * absent stance means; `auto` skips the profile, so a write runs on
+       * its own unless a rule or the capability's own declaration holds it.
+       */
+      export type AgentStance = 'ask' | 'observe' | 'assist' | 'auto';
+
       /**
        * Input to a single agent run. The catalog the model may call is
        * narrowed by `toolFilter` (Faz 2 ships a curated subset; the full
@@ -325,6 +389,24 @@ declare module 'punica' {
          * could join them. Contract: `docs/agent-loops.md`.
          */
         trace?: { traceId: string; parentSpanId?: string };
+        /**
+         * The run's stance (see {@link AgentStance}). Omitted ⇒ `assist`,
+         * which is what every run was before stances existed. Recorded on
+         * `ai.agentStarted` and carried to the gate on the run's policy
+         * context, so the trail says under which stance a call was decided.
+         */
+        stance?: AgentStance;
+        /**
+         * The AI core that answers this run, in the form `llms.activeCore`
+         * writes: `local:<id>` or `remote:<id>`. Omitted ⇒ the active core,
+         * exactly as before. Carried on every model call of the run as the
+         * request's `providerId`, so the host dispatches to that core (a
+         * remote one through the directory `extension-llms` publishes as
+         * `llm.remote.routes`) and the egress guard judges the run by it;
+         * recorded on `ai.agentStarted` as `coreId`. One model per task is
+         * this field (Agent Mode §9, `docs/agent-loops.md`).
+         */
+        coreId?: string;
         /**
          * Optional capability catalog filter (mirrors
          * `capability.schemaExport`'s filter shape). When omitted, the
@@ -680,6 +762,14 @@ declare module 'punica' {
         getPendingApprovals(): PendingApproval[];
         approvePending(pendingId: string, scope: kernel.ApprovalScope): boolean;
         dismissPending(pendingId: string): boolean;
+        /**
+         * Hand a pending question back with different arguments. No grant
+         * and no decline is written; the loop that asked dispatches again
+         * with the person's arguments and the gate asks anew, so an edit is
+         * a new question (a new `argsBinding`) and never an edited grant.
+         * Refused (`false`) when `edited` is not a plain object.
+         */
+        editPending(pendingId: string, edited: unknown): boolean;
         /**
          * Run the agentic tool-use loop: the model repeatedly decides on
          * capabilities to call as tools, the loop dispatches them through

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

@@ -30,6 +30,14 @@ declare module 'punica' {
        * key exactly as they did before actions existed.
        */
       action?: CapabilityAction[];
+      /**
+       * `'remote'` when the guarded call's payload would leave this
+       * machine, as the gateway's `egressGuard` resolved it before the
+       * gate asked. Absent for a call that stays here and for every
+       * request with no capability behind it. A rule with `egress:
+       * remote` reaches exactly the requests that carry this.
+       */
+      egress?: 'remote';
       risk: PolicyRisk;
       approval: PolicyApproval;
       /**
@@ -57,6 +65,13 @@ declare module 'punica' {
        * user consented to a hash they never saw.
        */
       argsPreview?: unknown;
+      /**
+       * The widest grant the rule in force accepts, set by the gate from
+       * the decision before it asks (`PolicyDecision.maxScope`) so the
+       * prompt offers no wider button and `approvePending` records no
+       * wider grant. Absent means the approver chooses.
+       */
+      maxScope?: ApprovalScope;
     }
 
     /**
@@ -188,6 +203,12 @@ declare module 'punica' {
       mode: PolicyMode;
       requiresApproval: boolean;
       suggestedScope?: ApprovalScope;
+      /**
+       * The widest grant the deciding `require` rule accepts (its
+       * `scope:`). Grants wider than this were not consulted. Absent
+       * when no rule wrote one.
+       */
+      maxScope?: ApprovalScope;
       reason?: string;
       /**
        * Set when a rule from a policy template decided this. Absent
@@ -460,11 +481,31 @@ declare module 'punica' {
        * `docs/capability-actions.md`.
        */
       action?: CapabilityAction[];
+      /**
+       * Selects the calls whose payload would leave this machine — a
+       * model call bound for a remote provider, a capability declaring
+       * `net.request` — as the gate resolved it. `deny egress: remote`
+       * is the sentence "no data leaves this machine" for every governed
+       * call; the direct model door is governed by `kind: llm.remote`
+       * (`docs/sensitive-data-egress.md`). The only value is `remote`.
+       */
+      egress?: 'remote';
       effect: PolicyRuleEffect;
       /** ANDed. Absent or empty matches every argument tuple. */
       when?: PolicyCondition[];
       /** Which approval `effect: 'require'` demands. Default `step`. */
       approval?: 'none' | 'plan' | 'step';
+      /**
+       * The widest grant that satisfies this rule, only on
+       * `effect: 'require'`. `once` means every call is asked about;
+       * `workspace` lets a project-wide grant stand and ignores an
+       * `always`; absent is `always`, which is what every rule written
+       * before this field meant — the approver chooses. An approver may
+       * go below the rule's scope and never above it: a wider grant on
+       * the store is simply not consulted, so tightening a rule takes
+       * effect on the next call without anyone revoking anything.
+       */
+      scope?: ApprovalScope;
       /** Shown to the user on a denial and written into the audit record. */
       reason?: string;
     }
@@ -477,6 +518,8 @@ declare module 'punica' {
       ruleIndex: number;
       effect: PolicyRuleEffect;
       reason?: string;
+      /** The rule's `scope`, when it wrote one (`effect: require` only). */
+      scope?: ApprovalScope;
       /** Digest of the template's rules — which policy text was in force. */
       digest?: string;
       /**
@@ -484,7 +527,7 @@ declare module 'punica' {
        * declares. A reader of the audit record can otherwise not tell
        * why a rule naming no id applied to this call.
        */
-      matchedBy?: 'id' | 'action';
+      matchedBy?: 'id' | 'action' | 'egress';
     }
 
     /** A rule that matched, plus the rule itself for the caller to read. */

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

@@ -61,6 +61,13 @@ declare module 'punica' {
       mode: 'suggest' | 'execute';
       /** Approval token (if approval was granted) */
       approvalToken?: string;
+      /**
+       * The agent run's stance, set by the kernel loop from
+       * `AgentRunInput.stance` and read by the gate's agent-mode rule alone
+       * (`kernel.AI.AgentStance`). Meaningful only for an `ai` actor; absent
+       * means the profile as it stands.
+       */
+      stance?: 'ask' | 'observe' | 'assist' | 'auto';
     }
 
     /**

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

@@ -423,6 +423,18 @@ declare module 'punica' {
        * this to gate which dispatches the provider can serve.
        */
       capabilities: Set<LlmProviderCapability>;
+      /**
+       * Where a request would run, said BEFORE dispatch: `'local'` when
+       * the answer stays on this machine, `'remote'` when it leaves it,
+       * nothing when the provider cannot say. Read by the facade's remote
+       * gate and the gateway's `egressGuard` after the request's own
+       * `route` / `providerId` and before the provider's `id`; a provider
+       * that says nothing is judged by its id, and one with no id either
+       * is treated as remote (`docs/sensitive-data-egress.md`).
+       */
+      describeDestination?(
+        req: LlmChatRequest
+      ): 'local' | 'remote' | undefined | Promise<'local' | 'remote' | undefined>;
       chat(req: LlmChatRequest): Promise<LlmChatResponse>;
       /**
        * Streaming chat. Optional — providers that don't support
@@ -608,6 +620,10 @@ declare module 'punica' {
 
     export interface LlmApi {
       chat(req: LlmChatRequest): Promise<LlmChatResponse>;
+      /** See `LlmProvider.describeDestination`; a host registers an `LlmApi`. */
+      describeDestination?(
+        req: LlmChatRequest
+      ): 'local' | 'remote' | undefined | Promise<'local' | 'remote' | undefined>;
       /**
        * Optional streaming chat. Hosts that back a streaming-capable
        * provider expose it here; the substrate runtime facade wraps it

package/types/punica.module.shell.profile.d.ts

@@ -163,10 +163,20 @@ declare module 'punica' {
          * during bootstrap. Kernel and runtime modules are always registered
          * unconditionally.
          *
-         * Structural DOM slots are derived from this list:
-         * - `shell.activityBar` → creates `activityBar` slot
-         * - `shell.view` → creates `primarySidebar` + `contentSidebar` slots
-         * - `shell.statusbar` → creates `statusbar` slot
+         * Structural DOM slots are derived from this list
+         * (`presentedSlots()` in `@punica/editor` is the one definition):
+         * - `shell.activityBar` → `activityBar`, `primarySidebar` and
+         *   `contentSidebar` — the strip is the only gesture that opens a
+         *   primary sidebar, and the content drawer is anchored beside it
+         *   (until 2026-09-26 the two sidebars followed `shell.view`, which
+         *   every profile activates for its helpers, so a window with no
+         *   strip got a sidebar nothing could open)
+         * - `shell.statusbar` → `statusbar`
+         *
+         * A view whose declared home slot the profile does not present is
+         * placed as a tab in the `content` slot, on demand — the extension
+         * analysis decorator applies that rule, so an extension never reads
+         * the profile.
          */
         activeModules: ShellModuleId[];
         /**

package/types/punica.module.shell.views.d.ts

@@ -12,6 +12,13 @@ declare module 'punica' {
      * agents and MCP clients all converge on them).
      */
     export namespace Views {
+      /**
+       * Where a view can be placed. `content` is never a manifest home: it is
+       * where a view lands when the active profile presents none of the slot
+       * its manifest names (`homeSlot` keeps the declared one), and a view
+       * placed there is a content tab, opened by a reveal and closed like a
+       * document.
+       */
       export type ViewSlotId =
         | 'primarySidebar'
         | 'secondarySidebar'