@petriflow/gate 0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# @petriflow/gate
+
+Framework-agnostic Petri net gating for AI agent tool access control. Define safety constraints as Petri nets — tools are only allowed when an enabled transition permits them.
+
+Built on [`@petriflow/engine`](../engine). Used by [`@petriflow/pi-extension`](../pi-extension) (pi-mono) and [`@petriflow/openclaw`](../openclaw) (OpenClaw).
+
+## Why
+
+LLM agents need guardrails, but hardcoded allow/deny lists are too rigid and per-call confirmation is too noisy. Petri nets let you express **stateful** safety constraints: "allow delete only after a successful backup", "allow push only after commit", "allow sending a message only after reading the channel".
+
+This package provides the core gating logic with no framework dependencies — adapter packages wire it into specific agent runtimes.
+
+## Defining a skill net
+
+```ts
+import { defineSkillNet } from "@petriflow/gate";
+
+const toolApproval = defineSkillNet({
+  name: "tool-approval",
+  places: ["idle", "ready"],
+  terminalPlaces: [],
+  freeTools: ["ls", "read", "grep", "find"],  // Always allowed
+  initialMarking: { idle: 1, ready: 0 },
+  transitions: [
+    { name: "start", type: "auto", inputs: ["idle"], outputs: ["ready"] },
+    { name: "execShell", type: "manual", inputs: ["ready"], outputs: ["ready"], tools: ["bash"] },
+    { name: "execWrite", type: "manual", inputs: ["ready"], outputs: ["ready"], tools: ["write", "edit"] },
+  ],
+});
+```
+
+## Key concepts
+
+### Transition types
+
+- **`auto`** — fires immediately when the tool is called and the transition is enabled
+- **`manual`** — requires human approval via `ctx.confirm()` before firing
+
+### Free tools
+
+Tools listed in `freeTools` are always allowed regardless of net state. Use this for read-only, side-effect-free tools.
+
+### Tool mapping
+
+Split one physical tool into multiple virtual tools based on input content:
+
+```ts
+const net = defineSkillNet({
+  // ...
+  toolMapper: (event) => {
+    if (event.toolName !== "bash") return event.toolName;
+    const cmd = event.input.command as string;
+    if (/\bgit\s+commit\b/.test(cmd)) return "git-commit";
+    if (/\bgit\s+push\b/.test(cmd)) return "git-push";
+    return "bash";
+  },
+  freeTools: ["bash"],  // Plain bash is free
+  transitions: [
+    { name: "commit", type: "manual", inputs: ["working"], outputs: ["committed"], tools: ["git-commit"] },
+    { name: "push", type: "manual", inputs: ["committed"], outputs: ["working"], tools: ["git-push"] },
+  ],
+});
+```
+
+### Deferred transitions
+
+Allow the tool call immediately but only advance the net when the tool succeeds:
+
+```ts
+{
+  name: "backup",
+  type: "auto",
+  inputs: ["ready"],
+  outputs: ["backedUp"],
+  tools: ["backup"],
+  deferred: true,  // Fires on successful tool_result, not tool_call
+}
+```
+
+If the tool fails (`isError: true`), the transition doesn't fire and the marking stays unchanged.
+
+### Semantic validation
+
+Add domain-specific checks beyond what net structure alone enforces:
+
+```ts
+const net = defineSkillNet({
+  // ...
+  validateToolCall: (event, resolvedTool, transition, state) => {
+    if (resolvedTool === "destructive") {
+      const target = extractTarget(event.input);
+      const covered = state.meta.backedUpPaths.some(p => covers(p, target));
+      if (!covered) return { block: true, reason: `Target '${target}' not backed up` };
+    }
+  },
+  onDeferredResult: (event, resolvedTool, transition, state) => {
+    // Record metadata when a deferred transition resolves
+    state.meta.backedUpPaths.push(extractPath(event.input));
+  },
+});
+```
+
+## Using the gate
+
+### Single net (low-level)
+
+```ts
+import { handleToolCall, handleToolResult, createGateState, autoAdvance } from "@petriflow/gate";
+
+const state = createGateState(autoAdvance(net, { ...net.initialMarking }));
+
+const decision = await handleToolCall(
+  { toolCallId: "1", toolName: "bash", input: { command: "rm -rf build/" } },
+  { hasUI: true, confirm: async (title, msg) => window.confirm(msg) },
+  net,
+  state,
+);
+
+if (decision?.block) {
+  console.log(`Blocked: ${decision.reason}`);
+}
+```
+
+### Multi-net composition (GateManager)
+
+```ts
+import { createGateManager } from "@petriflow/gate";
+
+// Static — all nets always active
+const manager = createGateManager([netA, netB]);
+
+// Registry — dynamic activation/deactivation
+const manager = createGateManager({
+  registry: { netA, netB, netC },
+  active: ["netA"],
+});
+
+const decision = await manager.handleToolCall(event, ctx);
+manager.handleToolResult(resultEvent);
+manager.addNet("netB");     // Registry mode only
+manager.removeNet("netA");  // Registry mode only
+manager.formatStatus();     // "netA (active): ready:1\nnetB (inactive): idle:1"
+manager.formatSystemPrompt(); // Markdown for LLM context
+```
+
+### Composition semantics
+
+When multiple nets are composed, each net independently classifies a tool call:
+
+| Verdict | Meaning |
+|---|---|
+| **free** | Tool is in the net's `freeTools` — always allowed |
+| **abstain** | Tool doesn't appear in any of the net's transitions — no opinion |
+| **gated** | An enabled transition covers this tool — allowed (pending approval/validation) |
+| **blocked** | The net has jurisdiction but no enabled transition — rejected |
+
+One **blocked** verdict from any net rejects the call. If no net blocks, **gated** nets fire their transitions. If all nets are **free** or **abstain**, the call passes through.
+
+## API
+
+| Export | Description |
+|---|---|
+| `defineSkillNet(config)` | Type-safe skill net constructor |
+| `createGateManager(input)` | Multi-net manager (array or registry config) |
+| `handleToolCall(event, ctx, net, state)` | Single-net tool call gating |
+| `handleToolResult(event, net, state)` | Single-net deferred resolution |
+| `autoAdvance(net, marking)` | Fire structural (non-tool) auto transitions |
+| `createGateState(marking)` | Initialize gate state with marking |
+| `classifyNets(nets, states, event)` | Phase 1 structural check (non-mutating) |
+| `composedToolCall(getNets, getStates, event, ctx)` | Full 4-phase composed gating |
+| `formatMarking(marking)` | Format marking for display (`"ready:1, working:0"`) |
+| `getEnabledToolTransitions(net, marking)` | List currently available tool transitions |
+| `resolveTool(net, event)` | Apply tool mapper |
+
+## Tests
+
+```bash
+bun test packages/gate
+```

package/dist/advance.d.ts

@@ -0,0 +1,11 @@
+import type { Marking } from "@petriflow/engine";
+import type { SkillNet } from "./types.js";
+/**
+ * Auto-advance: fire all enabled structural transitions (type=auto,
+ * no tools) in a loop until quiescent.
+ *
+ * When multiple structural transitions compete for the same input
+ * token, none of them fire (avoids ambiguous choices).
+ */
+export declare function autoAdvance<P extends string>(net: SkillNet<P>, marking: Marking<P>): Marking<P>;
+//# sourceMappingURL=advance.d.ts.map

package/dist/advance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advance.d.ts","sourceRoot":"","sources":["../src/advance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAmB,QAAQ,EAAE,MAAM,YAAY,CAAC;AA4B5D;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC1C,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,EAChB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAClB,OAAO,CAAC,CAAC,CAAC,CAwBZ"}

package/dist/advance.js

@@ -0,0 +1,49 @@
+import { canFire, fire } from "@petriflow/engine";
+/** A structural transition: type=auto, no tools property */
+function isStructural(t) {
+    return t.type === "auto" && (t.tools === undefined || t.tools.length === 0);
+}
+/**
+ * Check if two transitions compete for the same input token.
+ * Two transitions conflict if they share an input place and the
+ * marking doesn't have enough tokens for both.
+ */
+function hasInputConflict(a, b, marking) {
+    for (const place of a.inputs) {
+        if (b.inputs.includes(place)) {
+            // Count how many tokens each needs from this place
+            const aNeeds = a.inputs.filter((p) => p === place).length;
+            const bNeeds = b.inputs.filter((p) => p === place).length;
+            if ((marking[place] ?? 0) < aNeeds + bNeeds)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Auto-advance: fire all enabled structural transitions (type=auto,
+ * no tools) in a loop until quiescent.
+ *
+ * When multiple structural transitions compete for the same input
+ * token, none of them fire (avoids ambiguous choices).
+ */
+export function autoAdvance(net, marking) {
+    let current = { ...marking };
+    for (;;) {
+        const structural = net.transitions.filter((t) => isStructural(t) && canFire(current, t));
+        if (structural.length === 0)
+            break;
+        // Filter out transitions that conflict with another enabled one
+        const unambiguous = structural.filter((t) => structural.every((other) => other === t || !hasInputConflict(t, other, current)));
+        if (unambiguous.length === 0)
+            break;
+        for (const t of unambiguous) {
+            // Re-check enablement — earlier firings in this batch may have consumed tokens
+            if (canFire(current, t)) {
+                current = fire(current, t);
+            }
+        }
+    }
+    return current;
+}
+//# sourceMappingURL=advance.js.map

package/dist/advance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advance.js","sourceRoot":"","sources":["../src/advance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAIlD,4DAA4D;AAC5D,SAAS,YAAY,CAAmB,CAAqB;IAC3D,OAAO,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CACvB,CAAqB,EACrB,CAAqB,EACrB,OAAmB;IAEnB,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;QAC7B,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,mDAAmD;YACnD,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,MAAM,CAAC;YAC1D,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,MAAM,CAAC;YAC1D,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM;gBAAE,OAAO,IAAI,CAAC;QAC3D,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,GAAgB,EAChB,OAAmB;IAEnB,IAAI,OAAO,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;IAE7B,SAAS,CAAC;QACR,MAAM,UAAU,GAAG,GAAG,CAAC,WAAW,CAAC,MAAM,CACvC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAC9C,CAAC;QACF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM;QAEnC,gEAAgE;QAChE,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC1C,UAAU,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CACjF,CAAC;QACF,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM;QAEpC,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;YAC5B,+EAA+E;YAC/E,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC;gBACxB,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/compose.d.ts

@@ -0,0 +1,37 @@
+import type { GateToolCall, GateContext, GateDecision } from "./events.js";
+import type { SkillNet } from "./types.js";
+import type { GateState } from "./gate.js";
+/** Classification of a net's opinion on a tool call */
+export type NetVerdict<P extends string> = {
+    net: SkillNet<P>;
+    state: GateState<P>;
+    resolvedTool: string;
+} & ({
+    kind: "free";
+} | {
+    kind: "abstain";
+} | {
+    kind: "blocked";
+    reason: string;
+} | {
+    kind: "gated";
+    transition: SkillNet<P>["transitions"][number];
+});
+/** Registry-based config for dynamic net management */
+export type ComposeConfig = {
+    registry: Record<string, SkillNet<string>>;
+    active?: string[];
+};
+/**
+ * Phase 1 — Structural check (non-mutating).
+ * Classify each net as free, gated, blocked, or abstain.
+ */
+export declare function classifyNets<P extends string>(nets: SkillNet<P>[], states: GateState<P>[], event: {
+    toolName: string;
+    input: Record<string, unknown>;
+}): NetVerdict<P>[];
+/**
+ * 4-phase tool call handler for composed nets.
+ */
+export declare function composedToolCall(getNets: () => SkillNet<string>[], getStates: () => GateState<string>[], event: GateToolCall, ctx: GateContext): Promise<GateDecision>;
+//# sourceMappingURL=compose.d.ts.map

package/dist/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAO3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,uDAAuD;AACvD,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI;IACzC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,CACA;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;CAAE,CACpE,CAAC;AAEF,uDAAuD;AACvD,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAeF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC3C,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,EACnB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,EACtB,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC1D,UAAU,CAAC,CAAC,CAAC,EAAE,CA8BjB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,QAAQ,CAAC,MAAM,CAAC,EAAE,EACjC,SAAS,EAAE,MAAM,SAAS,CAAC,MAAM,CAAC,EAAE,EACpC,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,YAAY,CAAC,CAqFvB"}

package/dist/compose.js

@@ -0,0 +1,112 @@
+import { fire } from "@petriflow/engine";
+import { autoAdvance } from "./advance.js";
+import { formatMarking, getEnabledToolTransitions, resolveTool, } from "./gate.js";
+/**
+ * Check if a net has jurisdiction over a tool — i.e. the tool appears
+ * in at least one transition's tools list (enabled or not).
+ */
+function hasJurisdiction(net, resolvedTool) {
+    return net.transitions.some((t) => t.tools !== undefined && t.tools.includes(resolvedTool));
+}
+/**
+ * Phase 1 — Structural check (non-mutating).
+ * Classify each net as free, gated, blocked, or abstain.
+ */
+export function classifyNets(nets, states, event) {
+    return nets.map((net, i) => {
+        const state = states[i];
+        const resolvedTool = resolveTool(net, event);
+        const base = { net, state, resolvedTool };
+        // Free tools always pass
+        if (net.freeTools.includes(resolvedTool)) {
+            return { ...base, kind: "free" };
+        }
+        // No jurisdiction → abstain
+        if (!hasJurisdiction(net, resolvedTool)) {
+            return { ...base, kind: "abstain" };
+        }
+        // Has jurisdiction — check enabled transitions
+        const enabled = getEnabledToolTransitions(net, state.marking);
+        const matching = enabled.filter((t) => t.tools.includes(resolvedTool));
+        if (matching.length === 0) {
+            return {
+                ...base,
+                kind: "blocked",
+                reason: `[${net.name}] Tool '${resolvedTool}' not available in current state. Marking: ${formatMarking(state.marking)}`,
+            };
+        }
+        return { ...base, kind: "gated", transition: matching[0] };
+    });
+}
+/**
+ * 4-phase tool call handler for composed nets.
+ */
+export async function composedToolCall(getNets, getStates, event, ctx) {
+    const nets = getNets();
+    const states = getStates();
+    // --- Phase 1: Structural check ---
+    const verdicts = classifyNets(nets, states, {
+        toolName: event.toolName,
+        input: event.input,
+    });
+    // If any net blocks, reject immediately
+    const blocked = verdicts.find((v) => v.kind === "blocked");
+    if (blocked) {
+        return { block: true, reason: blocked.reason };
+    }
+    const gated = verdicts.filter((v) => v.kind === "gated");
+    // No gated nets → all free/abstain → allow
+    if (gated.length === 0) {
+        return undefined;
+    }
+    // --- Phase 2: Manual approvals ---
+    for (const v of gated) {
+        if (v.transition.type === "manual") {
+            if (!ctx.hasUI) {
+                return {
+                    block: true,
+                    reason: `[${v.net.name}] Manual transition '${v.transition.name}' requires UI approval`,
+                };
+            }
+            const approved = await ctx.confirm(`Approve: ${v.transition.name} (${v.net.name})`, `Allow '${v.resolvedTool}' via transition '${v.transition.name}' in net '${v.net.name}'?`);
+            if (!approved) {
+                return {
+                    block: true,
+                    reason: `[${v.net.name}] Human rejected '${v.transition.name}'`,
+                };
+            }
+        }
+    }
+    // --- Phase 3: Semantic validation with meta rollback ---
+    // Snapshot all meta for rollback
+    const metaSnapshots = gated.map((v) => structuredClone(v.state.meta));
+    for (let i = 0; i < gated.length; i++) {
+        const v = gated[i];
+        if (v.net.validateToolCall) {
+            const rejection = v.net.validateToolCall({ toolName: event.toolName, input: event.input }, v.resolvedTool, v.transition, v.state);
+            if (rejection) {
+                // Rollback all meta that may have been mutated by earlier validates
+                for (let j = 0; j < i; j++) {
+                    gated[j].state.meta = metaSnapshots[j];
+                }
+                return rejection;
+            }
+        }
+    }
+    // --- Phase 4: Commit ---
+    for (const v of gated) {
+        if (v.transition.deferred) {
+            v.state.pending.set(event.toolCallId, {
+                toolCallId: event.toolCallId,
+                transition: v.transition,
+                resolvedTool: v.resolvedTool,
+            });
+        }
+        else {
+            v.state.marking = fire(v.state.marking, v.transition);
+            v.state.marking = autoAdvance(v.net, v.state.marking);
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=compose.js.map

package/dist/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,24 @@
+/** Generic tool call event — framework-agnostic */
+export type GateToolCall = {
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+};
+/** Generic tool result event — framework-agnostic */
+export type GateToolResult = {
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+    isError: boolean;
+};
+/** Generic context for gating decisions */
+export type GateContext = {
+    hasUI: boolean;
+    confirm: (title: string, message: string) => Promise<boolean>;
+};
+/** A gating decision: block with reason, or undefined to allow */
+export type GateDecision = {
+    block: true;
+    reason: string;
+} | undefined;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,2CAA2C;AAC3C,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/D,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC"}

package/dist/events.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":""}

package/dist/gate.d.ts

@@ -0,0 +1,39 @@
+import type { Marking } from "@petriflow/engine";
+import type { GateToolCall, GateToolResult, GateContext, GateDecision } from "./events.js";
+import type { GatedTransition, SkillNet } from "./types.js";
+/** Resolve the virtual tool name for a tool call event */
+export declare function resolveTool<P extends string>(net: SkillNet<P>, event: {
+    toolName: string;
+    input: Record<string, unknown>;
+}): string;
+/** Public: get tool transitions the agent can currently use */
+export declare function getEnabledToolTransitions<P extends string>(net: SkillNet<P>, marking: Marking<P>): GatedTransition<P>[];
+/** Format marking for display */
+export declare function formatMarking<P extends string>(marking: Marking<P>): string;
+/** A pending deferred transition awaiting tool_result */
+type PendingDeferred<P extends string> = {
+    toolCallId: string;
+    transition: GatedTransition<P>;
+    resolvedTool: string;
+};
+export type GateState<P extends string> = {
+    marking: Marking<P>;
+    /** Skill-specific metadata (e.g. backed-up paths) */
+    meta: Record<string, unknown>;
+    /** Deferred transitions waiting for tool_result */
+    pending: Map<string, PendingDeferred<P>>;
+};
+export declare function createGateState<P extends string>(marking: Marking<P>): GateState<P>;
+/**
+ * Core gating logic for a tool_call event.
+ * Mutates state.marking when a non-deferred transition fires.
+ * For deferred transitions, records pending and fires on tool_result.
+ */
+export declare function handleToolCall<P extends string>(event: GateToolCall, ctx: GateContext, net: SkillNet<P>, state: GateState<P>): Promise<GateDecision>;
+/**
+ * Handle a tool_result event. Fires deferred transitions on success.
+ * Returns void (tool_result handler doesn't block).
+ */
+export declare function handleToolResult<P extends string>(event: GateToolResult, net: SkillNet<P>, state: GateState<P>): void;
+export {};
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG5D,0DAA0D;AAC1D,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC1C,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,EAChB,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC1D,MAAM,CAQR;AAYD,+DAA+D;AAC/D,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,MAAM,EACxD,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,EAChB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAClB,eAAe,CAAC,CAAC,CAAC,EAAE,CAEtB;AAED,iCAAiC;AACjC,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAK3E;AAED,yDAAyD;AACzD,KAAK,eAAe,CAAC,CAAC,SAAS,MAAM,IAAI;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,MAAM,IAAI;IACxC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,mDAAmD;IACnD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;CAC1C,CAAC;AAEF,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAEnF;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,MAAM,EACnD,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,WAAW,EAChB,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,EAChB,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAClB,OAAO,CAAC,YAAY,CAAC,CAuDvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAC/C,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,EAChB,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAClB,IAAI,CA+BN"}

package/dist/gate.js

@@ -0,0 +1,103 @@
+import { canFire, fire } from "@petriflow/engine";
+import { autoAdvance } from "./advance.js";
+/** Resolve the virtual tool name for a tool call event */
+export function resolveTool(net, event) {
+    if (net.toolMapper) {
+        return net.toolMapper({
+            toolName: event.toolName,
+            input: event.input,
+        });
+    }
+    return event.toolName;
+}
+/** Return transitions that are structurally enabled and have a tools list */
+function enabledToolTransitions(net, marking) {
+    return net.transitions.filter((t) => t.tools !== undefined && t.tools.length > 0 && canFire(marking, t));
+}
+/** Public: get tool transitions the agent can currently use */
+export function getEnabledToolTransitions(net, marking) {
+    return enabledToolTransitions(net, marking);
+}
+/** Format marking for display */
+export function formatMarking(marking) {
+    return Object.entries(marking)
+        .filter(([, v]) => v > 0)
+        .map(([k, v]) => `${k}:${v}`)
+        .join(", ");
+}
+export function createGateState(marking) {
+    return { marking, meta: {}, pending: new Map() };
+}
+/**
+ * Core gating logic for a tool_call event.
+ * Mutates state.marking when a non-deferred transition fires.
+ * For deferred transitions, records pending and fires on tool_result.
+ */
+export async function handleToolCall(event, ctx, net, state) {
+    const resolvedTool = resolveTool(net, event);
+    // Free tools always pass
+    if (net.freeTools.includes(resolvedTool)) {
+        return undefined;
+    }
+    const enabled = enabledToolTransitions(net, state.marking);
+    const matching = enabled.filter((t) => t.tools.includes(resolvedTool));
+    if (matching.length === 0) {
+        return {
+            block: true,
+            reason: `Tool '${resolvedTool}' not available in current state. Marking: ${formatMarking(state.marking)}`,
+        };
+    }
+    const transition = matching[0];
+    // Skill-specific validation (e.g. path coverage)
+    if (net.validateToolCall) {
+        const rejection = net.validateToolCall({ toolName: event.toolName, input: event.input }, resolvedTool, transition, state);
+        if (rejection)
+            return rejection;
+    }
+    if (transition.type === "manual") {
+        if (!ctx.hasUI) {
+            return { block: true, reason: `Manual transition '${transition.name}' requires UI approval` };
+        }
+        const approved = await ctx.confirm(`Approve: ${transition.name}`, `Allow '${resolvedTool}' via transition '${transition.name}'?`);
+        if (!approved) {
+            return { block: true, reason: `Human rejected '${transition.name}'` };
+        }
+    }
+    if (transition.deferred) {
+        // Allow the tool call but don't fire yet — wait for tool_result
+        state.pending.set(event.toolCallId, { toolCallId: event.toolCallId, transition, resolvedTool });
+        return undefined;
+    }
+    // Fire immediately
+    state.marking = fire(state.marking, transition);
+    state.marking = autoAdvance(net, state.marking);
+    return undefined;
+}
+/**
+ * Handle a tool_result event. Fires deferred transitions on success.
+ * Returns void (tool_result handler doesn't block).
+ */
+export function handleToolResult(event, net, state) {
+    const pending = state.pending.get(event.toolCallId);
+    if (!pending)
+        return;
+    state.pending.delete(event.toolCallId);
+    if (event.isError) {
+        // Tool failed — don't fire the transition, marking unchanged
+        return;
+    }
+    // Tool succeeded — fire the deferred transition
+    if (canFire(state.marking, pending.transition)) {
+        state.marking = fire(state.marking, pending.transition);
+        // Notify the skill of the successful deferred result
+        if (net.onDeferredResult) {
+            net.onDeferredResult({
+                toolCallId: event.toolCallId,
+                input: event.input,
+                isError: event.isError,
+            }, pending.resolvedTool, pending.transition, state);
+        }
+        state.marking = autoAdvance(net, state.marking);
+    }
+}
+//# sourceMappingURL=gate.js.map

package/dist/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { defineSkillNet } from "./types.js";
+export type { SkillNet, GatedTransition, ToolEvent } from "./types.js";
+export type { GateToolCall, GateToolResult, GateContext, GateDecision } from "./events.js";
+export { autoAdvance } from "./advance.js";
+export { handleToolCall, handleToolResult, formatMarking, getEnabledToolTransitions, createGateState, resolveTool, } from "./gate.js";
+export type { GateState } from "./gate.js";
+export { classifyNets, composedToolCall } from "./compose.js";
+export type { ComposeConfig, NetVerdict } from "./compose.js";
+export { createGateManager } from "./manager.js";
+export type { GateManager, GateManagerOptions } from "./manager.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3F,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,yBAAyB,EACzB,eAAe,EACf,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC9D,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+// Types
+export { defineSkillNet } from "./types.js";
+// Auto-advance
+export { autoAdvance } from "./advance.js";
+// Single-net gating
+export { handleToolCall, handleToolResult, formatMarking, getEnabledToolTransitions, createGateState, resolveTool, } from "./gate.js";
+// Multi-net composition
+export { classifyNets, composedToolCall } from "./compose.js";
+// Manager
+export { createGateManager } from "./manager.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAM5C,eAAe;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,oBAAoB;AACpB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,yBAAyB,EACzB,eAAe,EACf,WAAW,GACZ,MAAM,WAAW,CAAC;AAGnB,wBAAwB;AACxB,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG9D,UAAU;AACV,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/manager.d.ts

@@ -0,0 +1,38 @@
+import type { GateToolCall, GateToolResult, GateContext, GateDecision } from "./events.js";
+import type { SkillNet } from "./types.js";
+import type { GateState } from "./gate.js";
+import type { ComposeConfig } from "./compose.js";
+export type GateManager = {
+    handleToolCall: (event: GateToolCall, ctx: GateContext) => Promise<GateDecision>;
+    handleToolResult: (event: GateToolResult) => void;
+    addNet: (name: string) => {
+        ok: boolean;
+        message: string;
+    };
+    removeNet: (name: string) => {
+        ok: boolean;
+        message: string;
+    };
+    getActiveNets: () => Array<{
+        name: string;
+        net: SkillNet<string>;
+        state: GateState<string>;
+    }>;
+    getAllNets: () => Array<{
+        name: string;
+        net: SkillNet<string>;
+        state: GateState<string>;
+        active: boolean;
+    }>;
+    formatStatus: () => string;
+    formatSystemPrompt: () => string;
+    isDynamic: boolean;
+};
+export type GateManagerOptions = {
+    /** "enforce" blocks disallowed tools. "shadow" logs but never blocks. */
+    mode: "enforce" | "shadow";
+    /** Called after every gating decision. Use for logging, metrics, debugging. */
+    onDecision?: (event: GateToolCall, decision: GateDecision) => void;
+};
+export declare function createGateManager(input: SkillNet<string>[] | ComposeConfig, opts?: GateManagerOptions): GateManager;
+//# sourceMappingURL=manager.d.ts.map

package/dist/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAS3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,MAAM,WAAW,GAAG;IACxB,cAAc,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACjF,gBAAgB,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAClD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,aAAa,EAAE,MAAM,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;QAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9F,UAAU,EAAE,MAAM,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;QAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC5G,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,MAAM,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,yEAAyE;IACzE,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC3B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;CACpE,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,aAAa,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAgBnH"}

package/dist/manager.js

@@ -0,0 +1,128 @@
+import { createGateState, formatMarking, getEnabledToolTransitions, handleToolResult as handleToolResultSingle, } from "./gate.js";
+import { autoAdvance } from "./advance.js";
+import { composedToolCall } from "./compose.js";
+export function createGateManager(input, opts) {
+    const manager = Array.isArray(input) ? createArrayManager(input) : createRegistryManager(input);
+    if (opts) {
+        const original = manager.handleToolCall;
+        manager.handleToolCall = async (event, ctx) => {
+            const decision = await original.call(manager, event, ctx);
+            opts.onDecision?.(event, decision);
+            if (opts.mode === "shadow" && decision?.block) {
+                return undefined;
+            }
+            return decision;
+        };
+    }
+    return manager;
+}
+function createArrayManager(nets) {
+    const states = nets.map((net) => createGateState(autoAdvance(net, { ...net.initialMarking })));
+    const getNets = () => nets;
+    const getStates = () => states;
+    return {
+        handleToolCall(event, ctx) {
+            return composedToolCall(getNets, getStates, event, ctx);
+        },
+        handleToolResult(event) {
+            for (let i = 0; i < nets.length; i++) {
+                handleToolResultSingle(event, nets[i], states[i]);
+            }
+        },
+        addNet() {
+            return { ok: false, message: "Static composition does not support dynamic nets" };
+        },
+        removeNet() {
+            return { ok: false, message: "Static composition does not support dynamic nets" };
+        },
+        getActiveNets() {
+            return nets.map((net, i) => ({ name: net.name, net, state: states[i] }));
+        },
+        getAllNets() {
+            return nets.map((net, i) => ({ name: net.name, net, state: states[i], active: true }));
+        },
+        formatStatus() {
+            return nets
+                .map((n, i) => `${n.name}: ${formatMarking(states[i].marking)}`)
+                .join("\n");
+        },
+        formatSystemPrompt() {
+            return formatPromptForNets(nets, states);
+        },
+        isDynamic: false,
+    };
+}
+function createRegistryManager(config) {
+    const registry = new Map();
+    for (const [name, net] of Object.entries(config.registry)) {
+        registry.set(name, {
+            net,
+            state: createGateState(autoAdvance(net, { ...net.initialMarking })),
+        });
+    }
+    const activeNames = new Set(config.active ?? Object.keys(config.registry));
+    const getActiveNets = () => [...activeNames].map((n) => registry.get(n).net);
+    const getActiveStates = () => [...activeNames].map((n) => registry.get(n).state);
+    return {
+        handleToolCall(event, ctx) {
+            return composedToolCall(getActiveNets, getActiveStates, event, ctx);
+        },
+        handleToolResult(event) {
+            for (const { net, state } of registry.values()) {
+                handleToolResultSingle(event, net, state);
+            }
+        },
+        addNet(name) {
+            if (!registry.has(name)) {
+                return { ok: false, message: `Unknown net '${name}'. Available: ${[...registry.keys()].join(", ")}` };
+            }
+            if (activeNames.has(name)) {
+                return { ok: false, message: `'${name}' is already active` };
+            }
+            activeNames.add(name);
+            return { ok: true, message: `Activated '${name}'` };
+        },
+        removeNet(name) {
+            if (!activeNames.has(name)) {
+                return { ok: false, message: `'${name}' is not active. Active: ${[...activeNames].join(", ")}` };
+            }
+            activeNames.delete(name);
+            return { ok: true, message: `Deactivated '${name}' (state preserved)` };
+        },
+        getActiveNets() {
+            return [...activeNames].map((name) => {
+                const entry = registry.get(name);
+                return { name, net: entry.net, state: entry.state };
+            });
+        },
+        getAllNets() {
+            return [...registry.entries()].map(([name, { net, state }]) => ({
+                name,
+                net,
+                state,
+                active: activeNames.has(name),
+            }));
+        },
+        formatStatus() {
+            return [...registry.entries()]
+                .map(([name, { state }]) => {
+                const status = activeNames.has(name) ? "active" : "inactive";
+                return `${name} (${status}): ${formatMarking(state.marking)}`;
+            })
+                .join("\n");
+        },
+        formatSystemPrompt() {
+            return formatPromptForNets(getActiveNets(), getActiveStates());
+        },
+        isDynamic: true,
+    };
+}
+function formatPromptForNets(nets, states) {
+    const sections = nets.map((net, i) => {
+        const enabled = getEnabledToolTransitions(net, states[i].marking);
+        const toolList = enabled.flatMap((t) => t.tools ?? []);
+        return `### ${net.name}\nAvailable gated tools: ${toolList.join(", ") || "none"}\nFree tools: ${net.freeTools.join(", ")}\nState: ${formatMarking(states[i].marking)}`;
+    });
+    return `## Active Petri Nets (composed)\n${sections.join("\n\n")}`;
+}
+//# sourceMappingURL=manager.js.map

package/dist/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+import type { Marking } from "@petriflow/engine";
+/** A transition that optionally gates tool access */
+export type GatedTransition<Place extends string> = {
+    name: string;
+    type: "auto" | "manual";
+    inputs: Place[];
+    outputs: Place[];
+    guard?: string | null;
+    tools?: string[];
+    /**
+     * When true, the transition allows the tool call immediately but
+     * only fires (consumes/produces tokens) when the tool_result
+     * comes back successfully (isError === false).
+     * Use this for transitions where the tool must succeed before
+     * the net advances (e.g. backup must succeed before delete unlocks).
+     */
+    deferred?: boolean;
+};
+/** Minimal tool event shape for toolMapper */
+export type ToolEvent = {
+    toolName: string;
+    input: Record<string, unknown>;
+};
+/** A Petri net that gates a skill's tool access */
+export type SkillNet<Place extends string> = {
+    name: string;
+    places: Place[];
+    transitions: GatedTransition<Place>[];
+    initialMarking: Marking<Place>;
+    terminalPlaces: Place[];
+    freeTools: string[];
+    /**
+     * Maps a tool call to a virtual tool name before gating.
+     * Use this to split one tool (e.g. "bash") into multiple gated
+     * variants (e.g. "bash", "git-commit", "git-push") based on input.
+     * If not provided, event.toolName is used as-is.
+     */
+    toolMapper?: (event: ToolEvent) => string;
+    /**
+     * Additional validation before a gated tool call is allowed.
+     * Called after the net confirms a matching transition exists.
+     * Return { block, reason } to reject, or void to allow.
+     * Use this for domain-specific checks (e.g. path coverage).
+     *
+     * Method syntax is intentional — bivariant so SkillNet<Place> widens to SkillNet<string>.
+     */
+    validateToolCall?(event: ToolEvent, resolvedTool: string, transition: GatedTransition<Place>, state: {
+        marking: Marking<Place>;
+        meta: Record<string, unknown>;
+    }): {
+        block: true;
+        reason: string;
+    } | void;
+    /**
+     * Called when a deferred transition's tool_result arrives.
+     * Use this to record metadata (e.g. backed-up paths).
+     *
+     * Method syntax is intentional — bivariant so SkillNet<Place> widens to SkillNet<string>.
+     */
+    onDeferredResult?(event: {
+        toolCallId: string;
+        input: Record<string, unknown>;
+        isError: boolean;
+    }, resolvedTool: string, transition: GatedTransition<Place>, state: {
+        marking: Marking<Place>;
+        meta: Record<string, unknown>;
+    }): void;
+};
+/** Type-safe helper — validates places/marking at the type level */
+export declare function defineSkillNet<Place extends string>(net: SkillNet<Place>): SkillNet<Place>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,qDAAqD;AACrD,MAAM,MAAM,eAAe,CAAC,KAAK,SAAS,MAAM,IAAI;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,EAAE,KAAK,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,SAAS,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AAE7E,mDAAmD;AACnD,MAAM,MAAM,QAAQ,CAAC,KAAK,SAAS,MAAM,IAAI;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,WAAW,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;IACtC,cAAc,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC/B,cAAc,EAAE,KAAK,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,MAAM,CAAC;IAC1C;;;;;;;OAOG;IACH,gBAAgB,CAAC,CACf,KAAK,EAAE,SAAS,EAChB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,eAAe,CAAC,KAAK,CAAC,EAClC,KAAK,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAChE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1C;;;;;OAKG;IACH,gBAAgB,CAAC,CACf,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAC/E,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,eAAe,CAAC,KAAK,CAAC,EAClC,KAAK,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAChE,IAAI,CAAC;CACT,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,KAAK,SAAS,MAAM,EACjD,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,GACnB,QAAQ,CAAC,KAAK,CAAC,CAEjB"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/** Type-safe helper — validates places/marking at the type level */
+export function defineSkillNet(net) {
+    return net;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAkEA,oEAAoE;AACpE,MAAM,UAAU,cAAc,CAC5B,GAAoB;IAEpB,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@petriflow/gate",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "test": "bun test",
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "lint": "oxlint src/"
+  },
+  "dependencies": {
+    "@petriflow/engine": "workspace:*"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joshuaisaact/petri-flow.git",
+    "directory": "packages/gate"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "^1",
+    "typescript": "^5.7"
+  }
+}