@provos/ironcurtain 0.10.0 → 0.12.0

package/dist/config/paths.d.ts

@@ -1,3 +1,4 @@
+import type { BundleId } from '../session/types.js';
 /**
  * Returns the IronCurtain home directory.
  * Defaults to ~/.ironcurtain, overridable via IRONCURTAIN_HOME env var.
@@ -7,6 +8,14 @@ export declare function getIronCurtainHome(): string;
  * Returns the sessions base directory: {home}/sessions/
  */
 export declare function getSessionsDir(): string;
+/**
+ * Filenames shared across session-scoped and workflow-state-scoped
+ * layouts. Centralized so the "single source of truth" for how session
+ * artifacts are named does not drift between helpers and call sites.
+ */
+export declare const SESSION_LOG_FILENAME = "session.log";
+export declare const SESSION_METADATA_FILENAME = "session-metadata.json";
+export declare const SESSION_STATE_FILENAME = "session-state.json";
 /**
  * Returns the session directory for a given session ID:
  *   {home}/sessions/{sessionId}/
@@ -47,6 +56,25 @@ export declare function getSessionLogPath(sessionId: string): string;
  *   {home}/sessions/{sessionId}/llm-interactions.jsonl
  */
 export declare function getSessionLlmLogPath(sessionId: string): string;
+/**
+ * Returns the trajectory-capture directory for a single-session
+ * standalone run:
+ *   {home}/sessions/{sessionId}/captures/
+ *
+ * Holds `{sessionId}.jsonl` and `manifest.jsonl` per
+ * docs/designs/mitm-token-trajectory-capture.md §7.
+ */
+export declare function getSessionCapturesDir(sessionId: string): string;
+/**
+ * Returns the JSONL file path for a single session's captured
+ * exchanges within `capturesDir`. Filename is `{sessionId}.jsonl`.
+ */
+export declare function getSessionCaptureFile(capturesDir: string, sessionId: string): string;
+/**
+ * Returns the manifest path within a captures directory:
+ *   {capturesDir}/manifest.jsonl
+ */
+export declare function getCaptureManifestFile(capturesDir: string): string;
 /**
  * Returns the auto-approver LLM interaction log path for a given session:
  *   {home}/sessions/{sessionId}/auto-approve-llm.jsonl
@@ -143,6 +171,20 @@ export declare function loadConstitutionText(packageBasePath: string): string;
  * Loads the combined constitution and returns its SHA-256 hex digest.
  */
 export declare function computeConstitutionHash(basePath: string): string;
+/**
+ * Returns the user workflows directory: {home}/workflows/
+ * Users can place custom workflow definitions here.
+ */
+export declare function getUserWorkflowsDir(): string;
+/**
+ * Returns the user-global skills directory: {home}/skills/
+ *
+ * Skills placed here are layered into every Docker session regardless
+ * of workflow or persona. See `src/skills/discovery.ts` for the
+ * resolution order (user-global → persona → workflow, last-wins on
+ * collision) and `docs/designs/skills-capability.md` for the format.
+ */
+export declare function getUserSkillsDir(): string;
 /**
  * Returns the OAuth directory: {home}/oauth/
  * Stores provider credentials and token files.
@@ -165,6 +207,14 @@ export declare function getOAuthCredentialsPath(providerId: string): string;
  * can communicate with a running daemon (e.g., add-job, run-job).
  */
 export declare function getDaemonSocketPath(): string;
+/**
+ * Returns the web UI state file path: {home}/web-ui.json
+ *
+ * The daemon writes connection info (port + auth token) here on startup
+ * so CLI commands (e.g., `observe`) can connect to the WebSocket server.
+ * The file is removed on daemon shutdown.
+ */
+export declare function getWebUiStatePath(): string;
 /**
  * Returns the jobs base directory: {home}/jobs/
  */
@@ -188,3 +238,170 @@ export declare function getJobWorkspaceDir(jobId: string): string;
  * {home}/jobs/{jobId}/runs/
  */
 export declare function getJobRunsDir(jobId: string): string;
+/**
+ * Returns the workflow runs base directory: {home}/workflow-runs/
+ */
+export declare function getWorkflowRunsDir(): string;
+/**
+ * Returns the directory for a specific workflow run:
+ * {home}/workflow-runs/{workflowId}/
+ */
+export declare function getWorkflowRunDir(workflowId: string): string;
+/**
+ * Returns the containers root for a workflow run:
+ *   {home}/workflow-runs/{workflowId}/containers/
+ *
+ * Each bundle (one Docker container + its MITM/Code-Mode proxies, CA,
+ * fake keys, audit log, and per-state artifacts) lives under
+ * `containers/<bundleId>/`. A single-scope workflow has one entry; a
+ * bifurcated workflow with distinct `containerScope` values has one
+ * entry per distinct scope.
+ */
+export declare function getWorkflowContainersDir(workflowId: string): string;
+/**
+ * Returns the outer directory for a single bundle within a workflow run:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/
+ *
+ * Contains the bundle's audit log, its inner `bundle/` directory with
+ * sockets/CA/fake keys/orientation, and the per-state `states/` tree.
+ */
+export declare function getBundleDir(workflowId: string, bundleId: BundleId): string;
+/**
+ * Returns the inner bundle artifact directory:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/bundle/
+ *
+ * Holds the bundle-scoped files that `DockerInfrastructure` manages:
+ * MCP/MITM sockets, CA cert, fake keys, orientation scripts, and the
+ * effective system prompt. Bind-mounted into the Docker container for
+ * the UDS endpoints.
+ */
+export declare function getBundleBundleDir(workflowId: string, bundleId: BundleId): string;
+/**
+ * Returns the per-bundle audit log path:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/audit.jsonl
+ *
+ * One audit file per bundle (coordinator). Each entry is tagged with
+ * the active `persona` so consumers can reconstruct per-persona /
+ * per-re-entry slices by scanning.
+ */
+export declare function getBundleAuditLogPath(workflowId: string, bundleId: BundleId): string;
+/**
+ * Returns the trajectory-capture directory for a workflow bundle:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/captures/
+ *
+ * Sits alongside the bundle's audit log; holds one `{sessionId}.jsonl`
+ * per state visit plus a shared `manifest.jsonl`. See
+ * docs/designs/mitm-token-trajectory-capture.md §7.
+ */
+export declare function getBundleCapturesDir(workflowId: string, bundleId: BundleId): string;
+/**
+ * Returns the per-bundle states root:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/states/
+ *
+ * Each agent state invocation (including re-entries) that borrows this
+ * bundle gets its own subdirectory keyed by `{stateId}.{N}`.
+ */
+export declare function getBundleStatesDir(workflowId: string, bundleId: BundleId): string;
+/**
+ * Returns the per-invocation artifact directory for a single state:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/states/{stateSlug}/
+ *
+ * Holds this invocation's `session.log` and `session-metadata.json`.
+ * `stateSlug` is `{stateId}.{N}` (e.g., `fetch.1`, `plan.2`).
+ */
+export declare function getInvocationDir(workflowId: string, bundleId: BundleId, stateSlug: string): string;
+/**
+ * Picks the next available `{prefix}.{N}` slug in `statesDir`, where `prefix` is
+ * `stateId` or — when a fan-out `laneId` is supplied — `{stateId}_lane_{laneId}`.
+ * Returns `{prefix}.1` when no matching dir exists; otherwise the max existing
+ * N plus 1. Used so every state entry (true logical re-visits AND resume legs of
+ * a single visit) gets its own forensic dir — `session.log` and
+ * `session-metadata.json` no longer interleave across resume attempts.
+ *
+ * The `laneId` parameter is the fix for the fan-out artifact-dir collision: N
+ * same-state lanes run concurrently and, sharing one `stateId`, the check-then-act
+ * `{stateId}.{N}` computation races and clobbers each other's diagnostics. Keying
+ * the prefix on `lane.id` gives each lane its own `{stateId}_lane_{id}.{N}`
+ * namespace so per-lane `session.log` / `session-metadata.json` never collide.
+ *
+ * `laneId`, when supplied, MUST be a non-negative integer (the orchestrator
+ * assigns it as a fan-out loop index). It is interpolated into a directory-name
+ * prefix, so this is enforced as defense-in-depth on a path component: a
+ * non-integer or negative value throws (it would indicate an internal bug). A
+ * valid `laneId` renders as `_lane_<digits>`, which is path-safe and still
+ * passes the slug check.
+ */
+export declare function nextStateSlug(statesDir: string, stateId: string, laneId?: number): string;
+/**
+ * Returns the coordinator control socket path for a bundle:
+ *   {home}/run/{bundleId[0:12]}/ctrl.sock
+ *
+ * The coordinator listens on this UDS to accept policy hot-swap
+ * requests from the orchestrator. The socket sits under the bundle's
+ * per-bundle runtime root (mode `0o700`) so filesystem permissions
+ * gate access.
+ *
+ * The directory slug is truncated to 12 chars of `bundleId` so the
+ * assembled path fits under macOS `sockaddr_un.sun_path` (104 chars).
+ * 16^12 ≈ 2.8e14 combinations — collisions in the host-wide
+ * `run/<slug>/` namespace are astronomical.
+ */
+export declare function getBundleControlSocketPath(bundleId: BundleId): string;
+/**
+ * Returns the per-bundle runtime root directory:
+ *   {home}/run/{bundleId[0:12]}/
+ *
+ * Holds the coordinator control socket plus two subdirectories
+ * (`sockets/` and `host/`) so the bind-mounted UDS files can be
+ * co-located without exposing host-only sockets to the container.
+ */
+export declare function getBundleRuntimeRoot(bundleId: BundleId): string;
+/**
+ * Returns the per-bundle container-visible sockets directory:
+ *   {home}/run/{bundleId[0:12]}/sockets/
+ *
+ * Two UDS files live here:
+ *  - `proxy.sock`      (Code Mode proxy — bind-mounted into container)
+ *  - `mitm-proxy.sock` (MITM proxy      — bind-mounted into container)
+ *
+ * This directory is what `prepareDockerInfrastructure()` bind-mounts as
+ * `/run/ironcurtain/` inside the container (read-write). Only these two
+ * socket files live here — no audit logs, escalation files, or other
+ * session artifacts.
+ */
+export declare function getBundleSocketsDir(bundleId: BundleId): string;
+/**
+ * Returns the per-bundle host-only directory:
+ *   {home}/run/{bundleId[0:12]}/host/
+ *
+ * Holds UDS files that must NOT be visible to the container
+ * (currently just the MITM control socket).
+ */
+export declare function getBundleHostOnlyDir(bundleId: BundleId): string;
+/**
+ * Code Mode proxy UDS path for a bundle:
+ *   {home}/run/{bundleId[0:12]}/sockets/proxy.sock
+ *
+ * Bound by the host-side Code Mode proxy; reachable inside the
+ * container as `/run/ironcurtain/proxy.sock` via the bind mount on
+ * `getBundleSocketsDir()`.
+ */
+export declare function getBundleProxySocketPath(bundleId: BundleId): string;
+/**
+ * MITM proxy UDS path for a bundle:
+ *   {home}/run/{bundleId[0:12]}/sockets/mitm-proxy.sock
+ *
+ * Bound by the host-side MITM proxy; reachable inside the container as
+ * `/run/ironcurtain/mitm-proxy.sock` via the bind mount on
+ * `getBundleSocketsDir()`.
+ */
+export declare function getBundleMitmProxySocketPath(bundleId: BundleId): string;
+/**
+ * MITM control UDS path for a bundle:
+ *   {home}/run/{bundleId[0:12]}/host/mitm-control.sock
+ *
+ * Host-local only — lives under `host/` rather than `sockets/` so the
+ * bind mount that exposes `sockets/` at `/run/ironcurtain/` does not
+ * expose this socket to the container.
+ */
+export declare function getBundleMitmControlSocketPath(bundleId: BundleId): string;