@punica/editor 1.40.0 → 1.42.0

package/package.json

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

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

@@ -60,6 +60,24 @@ 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;
+        /**
+         * Who may answer (`kernel.PolicyRequest.approvers`). A card whose
+         * host identity matches no entry offers no grant and asks a
+         * reviewer instead.
+         */
+        approvers?: readonly string[];
+        /**
+         * Set by `referPending`: the question was handed to a reviewer
+         * outside this host, under this name. A run waiting on it holds
+         * for the reviewer's answer instead of timing out.
+         */
+        referredTo?: string;
         correlationId?: string;
         /**
          * Trace id of the invocation that hit the gate (an agent run id
@@ -86,6 +104,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 +150,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 +199,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 +347,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 +401,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
@@ -678,8 +772,37 @@ declare module 'punica' {
         runLastPlan(editedPlan?: AiPlan): Promise<AiRun>;
         getLastPlan(): AiPlan | null;
         getPendingApprovals(): PendingApproval[];
-        approvePending(pendingId: string, scope: kernel.ApprovalScope): boolean;
-        dismissPending(pendingId: string): boolean;
+        /**
+         * Record the grant a person made. `decider` names who, when the
+         * decision was made elsewhere and relayed by the host (a reviewer
+         * answering through the registry); absent, the host identity
+         * decides. Throws `APPROVER_NOT_ALLOWED` when the pending names
+         * approvers and the decider is none of them.
+         */
+        approvePending(
+          pendingId: string,
+          scope: kernel.ApprovalScope,
+          decider?: { decidedBy?: string; decidedRole?: string }
+        ): boolean;
+        dismissPending(
+          pendingId: string,
+          decider?: { decidedBy?: string; decidedRole?: string; reason?: string }
+        ): boolean;
+        /**
+         * Hand a pending question to a reviewer outside this host, by
+         * name (`role:ml-lead`, `user:<email>`, `owner`). Writes nothing
+         * to the store; publishes `ai.pendingApprovalReferred` so the run
+         * that asked waits for the answer instead of timing out.
+         */
+        referPending(pendingId: string, to: 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,20 @@ 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;
+      /**
+       * Who may answer, from the deciding rule's `approvers:` (set by the
+       * gate from `PolicyDecision.approvers`, like `maxScope`). A grant is
+       * consulted and recorded only under a decider one entry names;
+       * absent means anyone at this host may decide.
+       */
+      approvers?: readonly string[];
     }
 
     /**
@@ -150,6 +172,12 @@ declare module 'punica' {
       approval: PolicyApproval;
       reason?: string;
       decidedBy?: string;
+      /**
+       * Under which name the decider satisfied the rule's `approvers:`
+       * (`owner`, `role:ml-lead`, `user:<email>`). Absent on a grant no
+       * rule named approvers for.
+       */
+      decidedRole?: string;
       timestampMs: number;
       /**
        * Optional chain reference — Sub-step 3.L. When present,
@@ -188,6 +216,14 @@ 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;
+      /** The deciding `require` rule's `approvers:`, when it wrote them. */
+      approvers?: readonly string[];
       reason?: string;
       /**
        * Set when a rule from a policy template decided this. Absent
@@ -263,6 +299,15 @@ declare module 'punica' {
         ctx?: {
           workspaceId?: string;
           decidedBy?: string;
+          /**
+           * The name the decider decides under, when a trusted caller
+           * relays a decision made elsewhere (a reviewer answering
+           * through the registry): `owner`, `role:<name>` or
+           * `user:<email>`. With `req.approvers` set and this absent,
+           * the host identity's roles are matched instead; a decider
+           * no entry names is refused with `APPROVER_NOT_ALLOWED`.
+           */
+          decidedRole?: string;
           /**
            * Time-bound the approval — Sub-step 3.F. Epoch ms;
            * `hasApproval` rejects after this point. Undefined =
@@ -307,6 +352,8 @@ declare module 'punica' {
         ctx?: {
           workspaceId?: string;
           decidedBy?: string;
+          /** As on `recordApproval`: the name a relayed decider decided under. */
+          decidedRole?: string;
           /** Why, in the decider's words. Stored verbatim. */
           reason?: string;
           traceId?: string;
@@ -460,11 +507,40 @@ 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;
+      /**
+       * Who may answer, only on `effect: 'require'`: `owner`,
+       * `role:<name>` or `user:<email>`, any one of which is enough. A
+       * grant recorded by anyone else does not satisfy the rule, and a
+       * host whose identity matches no entry cannot grant it — it asks
+       * a reviewer instead. Absent means anyone at the host decides,
+       * which is what every rule written before this field meant.
+       */
+      approvers?: string[];
       /** Shown to the user on a denial and written into the audit record. */
       reason?: string;
     }
@@ -477,6 +553,10 @@ declare module 'punica' {
       ruleIndex: number;
       effect: PolicyRuleEffect;
       reason?: string;
+      /** The rule's `scope`, when it wrote one (`effect: require` only). */
+      scope?: ApprovalScope;
+      /** The rule's `approvers`, when it wrote them (`effect: require` only). */
+      approvers?: string[];
       /** Digest of the template's rules — which policy text was in force. */
       digest?: string;
       /**
@@ -484,7 +564,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.api.d.ts

@@ -235,6 +235,13 @@ declare module 'punica' {
        * invents nothing to fill it. Passing `undefined` clears it.
        */
       setHostIdentity: (identity: HostIdentity | undefined) => void;
+      /**
+       * The identity the host injected, or `undefined`. Read by a card
+       * deciding whether the person at this host may answer a rule that
+       * names its approvers (`roles`), and by a host asking a reviewer
+       * (`orgs`). Never a substitute for the audit record's `actor.id`.
+       */
+      getHostIdentity: () => HostIdentity | undefined;
 
       /**
        * Package signing. A host installs a signer during bootstrap so an
@@ -395,6 +402,15 @@ declare module 'punica' {
     export interface HostIdentity {
       email: string;
       displayName?: string | null;
+      /**
+       * The person's organisation roles, as the registry lists them
+       * (`owner`, `ml-lead`, …), across every organisation they belong
+       * to. Read by a `require` rule that names its `approvers:`; absent
+       * or empty means such a rule matches nobody at this host.
+       */
+      roles?: readonly string[];
+      /** The organisations behind those roles, for a host that asks a reviewer. */
+      orgs?: ReadonlyArray<{ id: string; name: string; role: string }>;
     }
 
     /**

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