usesteady 0.1.0-alpha.1

package/dist/src/cursor/types.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Cursor Integration types.
+ *
+ * ── Role of this module ────────────────────────────────────────────────────────
+ *
+ *   This module defines the seam between UseSteady's authority system and
+ *   Cursor's edit machinery. It is the type contract for:
+ *
+ *     - CursorHandoffArtifact: the approved, constrained artifact Cursor receives
+ *     - CursorDeliveryRequest: what the delivery gate sends to Cursor
+ *     - CursorResponse: the three response kinds Cursor may return
+ *     - CursorScopeQuestion: Cursor's structured scope clarification request
+ *     - CursorOCDPolicy: the policy inputs for the OCD evaluator
+ *
+ * ── Authority model ────────────────────────────────────────────────────────────
+ *
+ *   PROPOSE    parsedChange.filePath   (artifact mapper only)
+ *   CONSTRAIN  OCD policy engine       (conflicts + prohibitedPatterns)
+ *   REFINE     H at ready_for_confirmation (set from empty or narrow non-empty)
+ *   SELECT     H at scope_clarification (from Cursor's candidates only)
+ *
+ *   Cursor: execute only. No upstream reach-back. No re-interpretation.
+ *
+ * ── Key invariants ─────────────────────────────────────────────────────────────
+ *
+ *   - CursorHandoffArtifact never carries the original input string
+ *   - eligibility === "approved_for_cursor" is the only value that opens delivery
+ *   - H can set allowedFiles from empty or narrow non-empty; cannot widen non-empty
+ *   - H-provided paths are validated against workspace boundary (hard block)
+ *     and write_safe_globs (OCD conflict trigger)
+ *   - Maximum one scope clarification per delivery sequence
+ *
+ * ── Provenance chain ───────────────────────────────────────────────────────────
+ *
+ *   ucp.intent.v1 → ucp.response.v1 → ucp.cursor_handoff.v1
+ *     → ucp.cursor_receipt.v1
+ *       → [ucp.cursor_artifact.v1 — RESERVED FUTURE SLOT]
+ *         → ucp.execution_trace.v1 → ucp.replay_report.v1
+ *
+ *   Refusal path:
+ *     ucp.cursor_handoff.v1 → ucp.cursor_refused.v1 (dead end or retry trigger)
+ *
+ * See: docs/cursor-integration-architecture.md
+ *      docs/cursor-delivery-contract.md
+ *      docs/cursor-allowedfiles-policy.md
+ */
+export type CursorHandoffEligibility = 
+/** OCD cleared; awaiting H confirmation. */
+"pending_confirmation"
+/** H confirmed. Only value that opens the delivery gate. */
+ | "approved_for_cursor"
+/** H rejected, timed out, auto-rejected, or Cursor execution error. */
+ | "rejected";
+export type CursorOCDClearanceStatus = "cleared" | "conflict_detected" | "conflict_accepted";
+export type CursorOCDClearance = {
+    readonly status: CursorOCDClearanceStatus;
+    /** Policy rule IDs that were evaluated (from approval-workflow rule registry). */
+    readonly rulesFired: readonly string[];
+    /** Human-readable conflict descriptions. Empty when status === "cleared". */
+    readonly conflictsDetected: readonly string[];
+};
+export type CursorScopeConstraint = {
+    /**
+     * Files Cursor is allowed to touch.
+     *
+     * Empty ([]) = no explicit file restriction.
+     *   Semantic: Cursor may search freely within prohibitedPatterns.
+     *   H is shown this state and may specify a file before confirming.
+     *   OCD adds defensive prohibitedPatterns when this is empty.
+     *
+     * Non-empty = Cursor must stay within these paths.
+     *   Any write outside this set is an authority violation.
+     *   H may narrow (remove entries) but not widen (add entries).
+     *
+     * Populated by: artifact mapper from parsedChange.filePath.
+     * Refined by:   H (set from empty, or remove from non-empty).
+     * Never touched by: OCD (OCD fires conflicts; H decides).
+     */
+    readonly allowedFiles: readonly string[];
+    /**
+     * Named scopes within allowed files (function, class, component names).
+     * Empty = no sub-file restriction.
+     * Populated during scope clarification when questionKind === "need_scope_selection".
+     */
+    readonly allowedScopes: readonly string[];
+    /**
+     * Glob patterns Cursor must NOT touch, regardless of allowedFiles.
+     * Takes precedence over allowedFiles if there is overlap.
+     *
+     * Always contains defensive system globs (set by OCD policy):
+     *   migrations, .env files, secrets, lockfiles, generated code
+     * When allowedFiles is empty, also contains:
+     *   node_modules, .git
+     */
+    readonly prohibitedPatterns: readonly string[];
+};
+export type CursorChangeSpec = {
+    /**
+     * Category from whichever interpretation family ran.
+     *
+     * For execute + structured command (ParsedChange present):
+     *   InterpretationCategory values:
+     *   "tailwind_color_change" | "css_color_change" | "text_literal_change" | "config_value_change"
+     *
+     * For execute + intent interpretation (no ParsedChange):
+     *   IntentInterpretationCategory values:
+     *   "visual_color" | "text_change" | "config_change" | "workflow_operation" | "unknown"
+     */
+    readonly category: string;
+    /** Human-readable summary of what the change is. */
+    readonly summary: string;
+    /** Impact list from InterpretationResult. Empty for intent-only interpretations. */
+    readonly impact: readonly string[];
+    readonly confidence: "high" | "medium" | "low";
+    /**
+     * The parsed change directive.
+     *
+     * Present when mode === "execute" AND a structured command was parsed
+     * (i.e. InterpretationResult was produced — "replace X with Y in file").
+     *
+     * Absent for vague execute flows where only intent interpretation exists.
+     * When absent, Cursor has no concrete search string — the flow will likely
+     * reach Cursor and refuse (see Case C in allowedfiles-policy.md).
+     *
+     * When present: this is the primary edit directive. Cursor must use
+     * oldValue/newValue/filePath as the authoritative change spec.
+     * Cursor must not expand or paraphrase this.
+     */
+    readonly parsedChange?: {
+        readonly oldValue: string;
+        readonly newValue: string;
+        readonly filePath?: string;
+    };
+    /**
+     * Signals that produced the classification (from IntentInterpretation.basis
+     * or InterpretationResult category-specific evidence).
+     * Observability only — not an edit directive.
+     */
+    readonly basis: readonly string[];
+};
+export type CursorHandoffArtifact = {
+    /** Content-addressed identifier. Computed from artifact content, not delivery time. */
+    readonly id: string;
+    /** Links back to ucp.intent.v1 — the originating user intent. */
+    readonly intentId: string;
+    /** Links back to ucp.response.v1 — the intake mode decision. */
+    readonly responseId: string;
+    /**
+     * Mode authority — always "execute".
+     * Only intake mode === "execute" flows produce a CursorHandoffArtifact.
+     * Never re-derived by OCD, Present, or Cursor.
+     */
+    readonly mode: "execute";
+    /** What the edit is. Cursor uses this as the sole edit directive. */
+    readonly changeSpec: CursorChangeSpec;
+    /** OCD policy evaluation result. */
+    readonly ocdClearance: CursorOCDClearance;
+    /**
+     * Eligibility state.
+     * Only "approved_for_cursor" opens the delivery gate.
+     * Set exclusively by H — never by OCD, Present, or Cursor.
+     */
+    readonly eligibility: CursorHandoffEligibility;
+    /** What Cursor is allowed to touch. Set by OCD + optionally refined by H. */
+    readonly scopeConstraint: CursorScopeConstraint;
+    /**
+     * Epoch ms when H set eligibility to "approved_for_cursor".
+     * Absent until H approves.
+     * Omit entirely (do not set to undefined) per UCP undefined-free invariant.
+     */
+    readonly approvedAt?: number;
+};
+export type CursorOCDPolicy = {
+    /**
+     * Glob patterns that define the safe write zone.
+     * Files outside these globs trigger RULE_WRITE_OUTSIDE_WORKSPACE.
+     * Maps to write_safe_globs from the approval-workflow PolicyConfig.
+     */
+    readonly writeSafeGlobs: readonly string[];
+    /**
+     * Maximum number of files in allowedFiles before RULE_WRITE_TOO_MANY_FILES fires.
+     * Maps to max_files_approval_threshold from PolicyConfig.
+     */
+    readonly maxFilesApprovalThreshold: number;
+    /**
+     * Glob patterns always added to prohibitedPatterns regardless of allowedFiles.
+     * Example: ["**\/migrations\/**", "**\/.env*", "**\/secrets\/**", "*.lock"]
+     */
+    readonly alwaysProhibitedGlobs: readonly string[];
+    /**
+     * Additional globs added to prohibitedPatterns ONLY when allowedFiles is empty.
+     * Example: ["**\/node_modules\/**", "**\/.git\/**"]
+     */
+    readonly emptyAllowedFilesAdditionalProhibitions: readonly string[];
+    /**
+     * The workspace root path. Used for the H-provided path workspace-boundary check.
+     * H-provided paths outside this root are hard-blocked (not OCD conflicts).
+     */
+    readonly workspaceRoot: string;
+};
+export type CursorDeliveryRequest = {
+    /**
+     * Delivery-attempt identifier.
+     *
+     * IMPORTANT: This is an ATTEMPT identity, not a content identity.
+     *
+     *   deliveryId = sha256({ artifactId: artifact.id, sentAt })
+     *
+     * Unlike artifact.id (content-addressed, stable across re-deliveries),
+     * deliveryId is unique per delivery attempt. Use deliveryId for
+     * transport-level correlation only (ucp.cursor_receipt.v1, ucp.cursor_refused.v1).
+     * Never use deliveryId for content deduplication or provenance chain links —
+     * use artifact.id for those purposes.
+     */
+    readonly deliveryId: string;
+    /** Epoch ms when the delivery gate sent this request. */
+    readonly sentAt: number;
+    /**
+     * The approved artifact. Complete source of truth for the edit.
+     *
+     * Immutability rule: bit-for-bit identical to the artifact whose id was
+     * used to compute ucp.cursor_handoff.v1. If they diverge, the delivery
+     * is considered corrupted and must be aborted.
+     */
+    readonly artifact: CursorHandoffArtifact;
+};
+/**
+ * CursorAccepted — Cursor has taken ownership and will begin applying the edit.
+ *
+ * Does NOT mean the edit is complete — only that Cursor accepted the request.
+ * After returning Accepted, Cursor MUST apply the edit and MUST emit
+ * ucp.execution_trace.v1 when complete. Cursor MUST NOT surface a new
+ * confirmation request to H.
+ */
+export type CursorAccepted = {
+    readonly kind: "accepted";
+    readonly deliveryId: string;
+    readonly artifactId: string;
+    readonly receivedAt: number;
+};
+/**
+ * CursorRefusedDueToScope — Cursor cannot determine the edit target.
+ *
+ * Valid only when:
+ *   - parsedChange.filePath is absent AND Cursor found 0 or 2+ candidate files
+ *   - parsedChange.filePath is present but oldValue appears in multiple scopes
+ *
+ * Cursor MUST NOT have begun any file writes before returning this response.
+ * Triggers scope_clarification_needed state.
+ */
+export type CursorRefusedDueToScope = {
+    readonly kind: "refused_due_to_scope";
+    readonly deliveryId: string;
+    readonly artifactId: string;
+    readonly receivedAt: number;
+    readonly scopeQuestion: CursorScopeQuestion;
+};
+/**
+ * CursorRefusedDueToExecutionError — Cursor found the target but could not apply the edit.
+ *
+ * Cursor MUST NOT have written partial changes before returning this response.
+ * Triggers rejected state. No retry path.
+ */
+export type CursorRefusedDueToExecutionError = {
+    readonly kind: "refused_due_to_execution_error";
+    readonly deliveryId: string;
+    readonly artifactId: string;
+    readonly receivedAt: number;
+    readonly errorCode: CursorExecutionErrorCode;
+    /** Human-readable detail for Present layer. Must not contain raw stack traces. */
+    readonly detail: string;
+};
+export type CursorResponse = CursorAccepted | CursorRefusedDueToScope | CursorRefusedDueToExecutionError;
+/**
+ * CursorScopeQuestion — Cursor's structured scope clarification request.
+ *
+ * Not prose. The Present layer formats this for H.
+ * H selects from candidates — cannot add paths outside candidates.
+ */
+export type CursorScopeQuestionKind = "need_file_path" | "need_scope_selection" | "ambiguous_old_value";
+export type CursorScopeQuestion = {
+    readonly questionKind: CursorScopeQuestionKind;
+    /**
+     * Candidates Cursor found:
+     *   need_file_path:       relative file paths containing oldValue
+     *   need_scope_selection: scope names (function/class/component) within the file
+     *   ambiguous_old_value:  line numbers or context snippets
+     *
+     * Empty candidates = Cursor found nothing. This should produce
+     * refused_due_to_execution_error (errorCode: "old_value_not_found") instead.
+     */
+    readonly candidates: readonly string[];
+    /** What Cursor was searching for. Typically parsedChange.oldValue. */
+    readonly searchedFor: string;
+    /**
+     * Terse factual statement for the Present layer.
+     * Not a question — a statement of what was found.
+     * Example: "Found 'bg-blue-500' in 3 files. Select the target file."
+     */
+    readonly explanation: string;
+};
+export type CursorExecutionErrorCode = "old_value_not_found" | "ambiguous_match" | "file_not_found" | "scope_outside_allowed" | "prohibited_pattern_match" | "parse_error" | "merge_conflict" | "delivery_timeout";
+export type WorkspacePathValidationResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: "outside_workspace_boundary" | "invalid_path";
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/cursor/types.d.ts.map

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

package/dist/src/cursor/types.js

@@ -0,0 +1,48 @@
+/**
+ * Cursor Integration types.
+ *
+ * ── Role of this module ────────────────────────────────────────────────────────
+ *
+ *   This module defines the seam between UseSteady's authority system and
+ *   Cursor's edit machinery. It is the type contract for:
+ *
+ *     - CursorHandoffArtifact: the approved, constrained artifact Cursor receives
+ *     - CursorDeliveryRequest: what the delivery gate sends to Cursor
+ *     - CursorResponse: the three response kinds Cursor may return
+ *     - CursorScopeQuestion: Cursor's structured scope clarification request
+ *     - CursorOCDPolicy: the policy inputs for the OCD evaluator
+ *
+ * ── Authority model ────────────────────────────────────────────────────────────
+ *
+ *   PROPOSE    parsedChange.filePath   (artifact mapper only)
+ *   CONSTRAIN  OCD policy engine       (conflicts + prohibitedPatterns)
+ *   REFINE     H at ready_for_confirmation (set from empty or narrow non-empty)
+ *   SELECT     H at scope_clarification (from Cursor's candidates only)
+ *
+ *   Cursor: execute only. No upstream reach-back. No re-interpretation.
+ *
+ * ── Key invariants ─────────────────────────────────────────────────────────────
+ *
+ *   - CursorHandoffArtifact never carries the original input string
+ *   - eligibility === "approved_for_cursor" is the only value that opens delivery
+ *   - H can set allowedFiles from empty or narrow non-empty; cannot widen non-empty
+ *   - H-provided paths are validated against workspace boundary (hard block)
+ *     and write_safe_globs (OCD conflict trigger)
+ *   - Maximum one scope clarification per delivery sequence
+ *
+ * ── Provenance chain ───────────────────────────────────────────────────────────
+ *
+ *   ucp.intent.v1 → ucp.response.v1 → ucp.cursor_handoff.v1
+ *     → ucp.cursor_receipt.v1
+ *       → [ucp.cursor_artifact.v1 — RESERVED FUTURE SLOT]
+ *         → ucp.execution_trace.v1 → ucp.replay_report.v1
+ *
+ *   Refusal path:
+ *     ucp.cursor_handoff.v1 → ucp.cursor_refused.v1 (dead end or retry trigger)
+ *
+ * See: docs/cursor-integration-architecture.md
+ *      docs/cursor-delivery-contract.md
+ *      docs/cursor-allowedfiles-policy.md
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/cursor/types.js.map

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

package/dist/src/execution/claude/claude-execution-coordinator.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Claude Execution Coordinator — product seam wiring (Phase 8C).
+ *
+ * ── Purpose ───────────────────────────────────────────────────────────────────
+ *
+ *   The execution entry point for Claude Managed Agent requests.
+ *
+ *   Mirrors cursor-execution-coordinator.ts in structure:
+ *
+ *     prepareCursorExecution()    → prepareClaude Execution()
+ *     deliverCursorExecution()    → deliverClaudeExecution()
+ *
+ *   Two phases. Same intent-separation as Cursor:
+ *     Phase 1 (prepare): deterministic, synchronous, no side effects.
+ *                        Builds the artifact, evaluates OCD, returns confirmation state.
+ *     Phase 2 (deliver): async, requires H approval, dispatches to Claude API.
+ *                        Calls the delivery gate with an already-approved artifact.
+ *
+ * ── OCD evaluation for Claude ──────────────────────────────────────────────────
+ *
+ *   Claude OCD is simpler than Cursor OCD at V1.
+ *   The artifact already carries prohibitedPatterns from the mapper (ClaudeOCDPolicy).
+ *
+ *   The OCD check fires a conflict when parsedChange.filePath matches any
+ *   prohibitedPattern glob. This surfaces the conflict to H before delivery.
+ *   The delivery gate independently enforces prohibitedPatterns at delivery time
+ *   (defense-in-depth: gate is the hard block, OCD is the early warning).
+ *
+ * ── What this is NOT ──────────────────────────────────────────────────────────
+ *
+ *   NOT a scheduler       — does not queue or retry
+ *   NOT an OCD authority  — OCD fires conflicts; this surfaces them
+ *   NOT a decision maker  — all decisions flow from intake + OCD + H approval
+ *   NOT autonomous        — deliverClaudeExecution() requires an approved artifact
+ *
+ * ── Dependency direction ───────────────────────────────────────────────────────
+ *
+ *   Coordinator imports: intake types, claude module (all phases).
+ *   Claude module NEVER imports this coordinator.
+ *   Present layer NEVER imports this coordinator.
+ *
+ * ── Authority invariants preserved ────────────────────────────────────────────
+ *
+ *   - mode === "execute" is the only intake mode that opens Phase 1.
+ *   - eligibility === "approved_for_agent" is the only state that opens Phase 2.
+ *   - Raw input never crosses to Claude (enforced by ClaudeAgentHandoffArtifact shape).
+ *   - executionDomain is derived once in buildClaudeHandoffArtifact (A1).
+ *   - OCD fires conflicts; this surfaces them — never overrides them.
+ *   - H approval is explicit (approveClaudeArtifact before deliverClaudeExecution).
+ *
+ * See: docs/claude-agent-phase-a-architecture.md
+ */
+import type { IntakeResult } from "../../intake/types.js";
+import type { ReplaceChange } from "../../understand/interpretation/types.js";
+type ParsedChange = ReplaceChange;
+import type { ClaudeAgentHandoffArtifact, ClaudeOCDPolicy, ClaudeScopeQuestion, ClaudeToolPolicy } from "../../claude/index.js";
+import type { ClaudeAgentPlugin } from "../../claude/delivery-gate.js";
+import type { ClaudeGateDeps } from "../../claude/delivery-gate.js";
+/**
+ * ClaudePreparationResult — returned by prepareClaudeExecution().
+ *
+ *   "ready_for_confirmation"  OCD cleared. Artifact awaits H approval.
+ *   "conflict_detected"       OCD fired a conflict. H must review + acceptConflict before approving.
+ *   "not_execute"             intakeResult.mode was not "execute". No artifact produced.
+ */
+export type ClaudePreparationResult = {
+    readonly kind: "ready_for_confirmation";
+    readonly artifact: ClaudeAgentHandoffArtifact;
+    readonly display: ClaudePreparationDisplay;
+} | {
+    readonly kind: "conflict_detected";
+    readonly artifact: ClaudeAgentHandoffArtifact;
+    readonly display: ClaudePreparationDisplay;
+} | {
+    readonly kind: "not_execute";
+    readonly reason: string;
+};
+/**
+ * ClaudePreparationDisplay — consumer-ready strings for the Phase 1 result.
+ *
+ *   headline    — "Ready to delegate" / "Conflict detected"
+ *   summary     — task description (from taskSpec.summary)
+ *   targetFile  — the proposed target file from parsedChange, if known
+ *   conflicts   — human-readable OCD conflict messages; empty when cleared
+ */
+export type ClaudePreparationDisplay = {
+    readonly headline: string;
+    readonly summary: string;
+    readonly targetFile: string | null;
+    readonly conflicts: readonly string[];
+};
+/**
+ * ClaudeExecutionResult — returned by deliverClaudeExecution().
+ *
+ *   "accepted"                       Claude accepted the task and started a session.
+ *   "refused_due_to_scope"           Claude needs H to clarify scope.
+ *   "refused_due_to_execution_error" Claude could not proceed (network, auth, session error).
+ *   "blocked_ineligible"             Artifact not approved. Caller error.
+ *   "blocked_tool_policy"            Tool policy violation (networkAccess not "deny", etc.).
+ *   "blocked_persistence_failure"    Handoff provenance could not be recorded.
+ */
+export type ClaudeExecutionResult = {
+    readonly kind: "accepted";
+    readonly deliveryId: string;
+    readonly sessionId: string;
+    readonly display: ClaudeExecutionDisplay;
+} | {
+    readonly kind: "refused_due_to_scope";
+    readonly deliveryId: string;
+    readonly scopeQuestion: ClaudeScopeQuestion;
+    readonly display: ClaudeExecutionDisplay;
+} | {
+    readonly kind: "refused_due_to_execution_error";
+    readonly deliveryId: string;
+    readonly errorCode: string;
+    readonly detail: string;
+    readonly display: ClaudeExecutionDisplay;
+} | {
+    readonly kind: "blocked_ineligible";
+    readonly display: ClaudeExecutionDisplay;
+} | {
+    readonly kind: "blocked_tool_policy";
+    readonly reason: string;
+    readonly display: ClaudeExecutionDisplay;
+} | {
+    readonly kind: "blocked_persistence_failure";
+    readonly reason: string;
+    readonly display: ClaudeExecutionDisplay;
+};
+/**
+ * ClaudeExecutionDisplay — consumer-ready strings for the Phase 2 result.
+ */
+export type ClaudeExecutionDisplay = {
+    readonly verdict: "accepted" | "refused" | "blocked";
+    readonly headline: string;
+    readonly note: string | null;
+};
+/**
+ * Build and OCD-evaluate a ClaudeAgentHandoffArtifact from an IntakeResult.
+ *
+ * Returns a preparation result describing what will happen and whether OCD
+ * has any conflicts. Synchronous and side-effect-free.
+ *
+ * @param intakeResult  Output of runIntake(). Must have mode === "execute".
+ * @param intentId      UCP envelope id of the intent.
+ * @param responseId    UCP envelope id of the response.
+ * @param policy        OCD policy (alwaysProhibitedGlobs, writeSafeGlobs).
+ * @param toolPolicy    Tool policy (allowedTools, networkAccess, filesystemMode).
+ * @param parsedChange  Optional: structured change parsed from the input.
+ */
+export declare function prepareClaudeExecution(intakeResult: IntakeResult, intentId: string, responseId: string, policy: ClaudeOCDPolicy, toolPolicy: ClaudeToolPolicy, parsedChange?: ParsedChange): ClaudePreparationResult;
+/**
+ * Deliver an already-approved ClaudeAgentHandoffArtifact through the delivery gate.
+ *
+ * Call this after H has called approveClaudeArtifact() on the prepared artifact.
+ *
+ * @param approvedArtifact  A ClaudeAgentHandoffArtifact with eligibility: "approved_for_agent".
+ * @param plugin            The transport adapter (ClaudeApiAdapter or stub).
+ * @param storeDir          Absolute path to the UCP store directory.
+ * @param deps              Optional: injectable persistence fns for testing.
+ */
+export declare function deliverClaudeExecution(approvedArtifact: ClaudeAgentHandoffArtifact, plugin: ClaudeAgentPlugin, storeDir: string, deps?: ClaudeGateDeps): Promise<ClaudeExecutionResult>;
+export {};
+//# sourceMappingURL=claude-execution-coordinator.d.ts.map

package/dist/src/execution/claude/claude-execution-coordinator.d.ts.map

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