@petriflow/gate 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,209 @@
+import { Marking } from '@petriflow/engine';
+
+/** A transition that optionally gates tool access */
+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 */
+type ToolEvent = {
+    toolName: string;
+    input: Record<string, unknown>;
+};
+/** A Petri net that gates a skill's tool access */
+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 */
+declare function defineSkillNet<Place extends string>(net: SkillNet<Place>): SkillNet<Place>;
+
+/** Generic tool call event — framework-agnostic */
+type GateToolCall = {
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+};
+/** Generic tool result event — framework-agnostic */
+type GateToolResult = {
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+    isError: boolean;
+};
+/** Generic context for gating decisions */
+type GateContext = {
+    hasUI: boolean;
+    confirm: (title: string, message: string) => Promise<boolean>;
+};
+/** A gating decision: block with reason, or undefined to allow */
+type GateDecision = {
+    block: true;
+    reason: string;
+} | undefined;
+
+/**
+ * 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).
+ */
+declare function autoAdvance<P extends string>(net: SkillNet<P>, marking: Marking<P>): Marking<P>;
+
+/** Resolve the virtual tool name for a tool call event */
+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 */
+declare function getEnabledToolTransitions<P extends string>(net: SkillNet<P>, marking: Marking<P>): GatedTransition<P>[];
+/** Format marking for display */
+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;
+};
+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>>;
+};
+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.
+ */
+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).
+ */
+declare function handleToolResult<P extends string>(event: GateToolResult, net: SkillNet<P>, state: GateState<P>): void;
+
+/** Classification of a net's opinion on a tool call */
+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 */
+type ComposeConfig = {
+    registry: Record<string, SkillNet<string>>;
+    active?: string[];
+};
+/**
+ * Phase 1 — Structural check (non-mutating).
+ * Classify each net as free, gated, blocked, or abstain.
+ */
+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.
+ */
+declare function composedToolCall(getNets: () => SkillNet<string>[], getStates: () => GateState<string>[], event: GateToolCall, ctx: GateContext): Promise<GateDecision>;
+
+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;
+};
+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;
+};
+declare function createGateManager(input: SkillNet<string>[] | ComposeConfig, opts?: GateManagerOptions): GateManager;
+
+export { type ComposeConfig, type GateContext, type GateDecision, type GateManager, type GateManagerOptions, type GateState, type GateToolCall, type GateToolResult, type GatedTransition, type NetVerdict, type SkillNet, type ToolEvent, autoAdvance, classifyNets, composedToolCall, createGateManager, createGateState, defineSkillNet, formatMarking, getEnabledToolTransitions, handleToolCall, handleToolResult, resolveTool };

package/dist/index.d.ts

@@ -1,11 +1,209 @@
-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
+import { Marking } from '@petriflow/engine';
+
+/** A transition that optionally gates tool access */
+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 */
+type ToolEvent = {
+    toolName: string;
+    input: Record<string, unknown>;
+};
+/** A Petri net that gates a skill's tool access */
+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 */
+declare function defineSkillNet<Place extends string>(net: SkillNet<Place>): SkillNet<Place>;
+
+/** Generic tool call event — framework-agnostic */
+type GateToolCall = {
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+};
+/** Generic tool result event — framework-agnostic */
+type GateToolResult = {
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+    isError: boolean;
+};
+/** Generic context for gating decisions */
+type GateContext = {
+    hasUI: boolean;
+    confirm: (title: string, message: string) => Promise<boolean>;
+};
+/** A gating decision: block with reason, or undefined to allow */
+type GateDecision = {
+    block: true;
+    reason: string;
+} | undefined;
+
+/**
+ * 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).
+ */
+declare function autoAdvance<P extends string>(net: SkillNet<P>, marking: Marking<P>): Marking<P>;
+
+/** Resolve the virtual tool name for a tool call event */
+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 */
+declare function getEnabledToolTransitions<P extends string>(net: SkillNet<P>, marking: Marking<P>): GatedTransition<P>[];
+/** Format marking for display */
+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;
+};
+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>>;
+};
+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.
+ */
+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).
+ */
+declare function handleToolResult<P extends string>(event: GateToolResult, net: SkillNet<P>, state: GateState<P>): void;
+
+/** Classification of a net's opinion on a tool call */
+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 */
+type ComposeConfig = {
+    registry: Record<string, SkillNet<string>>;
+    active?: string[];
+};
+/**
+ * Phase 1 — Structural check (non-mutating).
+ * Classify each net as free, gated, blocked, or abstain.
+ */
+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.
+ */
+declare function composedToolCall(getNets: () => SkillNet<string>[], getStates: () => GateState<string>[], event: GateToolCall, ctx: GateContext): Promise<GateDecision>;
+
+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;
+};
+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;
+};
+declare function createGateManager(input: SkillNet<string>[] | ComposeConfig, opts?: GateManagerOptions): GateManager;
+
+export { type ComposeConfig, type GateContext, type GateDecision, type GateManager, type GateManagerOptions, type GateState, type GateToolCall, type GateToolResult, type GatedTransition, type NetVerdict, type SkillNet, type ToolEvent, autoAdvance, classifyNets, composedToolCall, createGateManager, createGateState, defineSkillNet, formatMarking, getEnabledToolTransitions, handleToolCall, handleToolResult, resolveTool };