@punica/editor 1.15.0 → 1.16.0

package/package.json

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

package/types/punica.module.flow.engine.d.ts

@@ -116,6 +116,15 @@ declare module 'punica' {
         risk: string;
         approval: string;
         reason?: string;
+        /**
+         * Argument binding carried from the gate — see
+         * `kernel.PolicyRequest.argsBinding`. Without it the approval
+         * recorded when this pending resolves covers every argument
+         * tuple for the step's capability, not just this step's.
+         */
+        argsBinding?: string;
+        /** Redacted view of the bound arguments, for the approval UI. */
+        argsPreview?: unknown;
         workspaceId?: string;
         timestampMs: number;
       }

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

@@ -46,6 +46,20 @@ declare module 'punica' {
         risk: string;
         approval: string;
         reason?: string;
+        /**
+         * The argument binding the gate computed for this call — see
+         * `kernel.PolicyRequest.argsBinding`. Carried across the round
+         * trip so `approvePending` grants for the arguments the user was
+         * shown rather than for the capability as a whole.
+         */
+        argsBinding?: string;
+        /**
+         * Redacted view of those arguments, so an approval prompt can
+         * show what is being bound. A user asked to allow
+         * `mcp.aws.deleteObject` without seeing the bucket is consenting
+         * to a name, not to an action.
+         */
+        argsPreview?: unknown;
         correlationId?: string;
         /**
          * Trace id of the invocation that hit the gate (an agent run id
@@ -509,7 +523,9 @@ declare module 'punica' {
        * history rather than fail a run.
        */
       export interface ToolUsageStore {
-        read(): Promise<Record<string, { calls: number; ok: number; last: number }>>;
+        read(): Promise<
+          Record<string, { calls: number; ok: number; last: number }>
+        >;
         record(capabilityId: string, ok: boolean, atMs: number): Promise<void>;
         forget(): Promise<void>;
       }

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

@@ -22,6 +22,27 @@ declare module 'punica' {
        * Optional human-readable reason shown in UI prompts.
        */
       reason?: string;
+      /**
+       * Which arguments this decision is about — a digest computed by
+       * `computeArgsBinding` from the capability's REDACTED input, or the
+       * literal `'any'` for a grant deliberately made argument-blind
+       * (an unattended-client pre-authorisation).
+       *
+       * Absent means the request has no argument dimension (`llm.remote`,
+       * a flow step). Absence keys exactly as it did before bindings
+       * existed, so those kinds re-prompt nothing.
+       *
+       * The field is what stops one "always" grant on
+       * `mcp.aws.deleteObject` from authorising every bucket.
+       */
+      argsBinding?: string;
+      /**
+       * Redacted, possibly truncated view of the bound arguments.
+       * Carried so an approval prompt can show what is being bound and
+       * an evidence package can read it back — a digest alone means the
+       * user consented to a hash they never saw.
+       */
+      argsPreview?: unknown;
     }
 
     /**
@@ -123,6 +144,15 @@ declare module 'punica' {
        * record + chain state by this id.
        */
       chainRef?: string;
+      /**
+       * The arguments this grant covers. See `PolicyRequest.argsBinding`.
+       * Persisted so a grant matches only the arguments it was given
+       * for, and so a reader can distinguish a bucket-specific approval
+       * from an `'any'` blanket one.
+       */
+      argsBinding?: string;
+      /** Redacted view of the bound arguments, for display and audit. */
+      argsPreview?: unknown;
       /**
        * Time-bounded approvals — Sub-step 3.F. Epoch ms after which
        * the approval is considered expired. `hasApproval` returns
@@ -191,8 +221,17 @@ declare module 'punica' {
         }
       ): ApprovalRecord;
 
+      /**
+       * `argsBinding` must be supplied when revoking a bound grant —
+       * omitting it targets the unbound key and silently revokes
+       * nothing, which is how a consumed "approve once" would turn into
+       * a permanent allow.
+       */
       revokeApproval(
-        rec: Pick<ApprovalRecord, 'kind' | 'id' | 'scope' | 'workspaceId'>
+        rec: Pick<
+          ApprovalRecord,
+          'kind' | 'id' | 'scope' | 'workspaceId' | 'argsBinding'
+        >
       ): boolean;
 
       /**
@@ -308,8 +347,41 @@ declare module 'punica' {
       isRevoked(jti: string): boolean;
     }
 
+    /** What `computeArgsBinding` returns. */
+    export interface ArgsBinding {
+      /** Digest of the bound arguments. */
+      binding: string;
+      /** Redacted, possibly truncated view of what was bound. */
+      preview: unknown;
+    }
+
     export namespace Policy {
       const manager: PolicyApi;
+
+      /**
+       * Literal binding meaning "any arguments" — a grant deliberately
+       * made argument-blind, as opposed to a request that has no
+       * argument dimension at all (absent binding).
+       */
+      const ARGS_BINDING_ANY: 'any';
+
+      /**
+       * Digest the arguments a decision is about.
+       *
+       * `source` must be the REDACTED input, so no secret value reaches
+       * the digest. `policyKeyPaths` narrows the binding to the declared
+       * fields, which is what makes an `always` grant practical; empty
+       * binds the whole argument tuple.
+       *
+       * An extension that pre-records a grant must call this rather than
+       * hashing locally — otherwise its key and the gate's key drift and
+       * the grant never matches. Throws when Web Crypto is unavailable
+       * rather than falling back to a weaker hash.
+       */
+      function computeArgsBinding(
+        source: unknown,
+        options?: { policyKeyPaths?: ReadonlyArray<ReadonlyArray<string>> }
+      ): Promise<ArgsBinding>;
     }
   }
 }