@sapiom/harness 0.0.0 → 0.1.1

package/dist/shared/types.d.ts

@@ -0,0 +1,485 @@
+/**
+ * Sapiom Harness — shared interface contract.
+ *
+ * Every workstream (terminal core, SPA, analytics, CLI, canvas) builds against
+ * the types in this file. Change them only by agreement — this file is the
+ * integration boundary.
+ */
+export declare const DEFAULT_PORT = 4100;
+/** All harness-owned state lives under this directory. Uninstall = delete it. */
+export declare const HARNESS_HOME = "~/.sapiom/harness";
+export declare const HARNESS_PATHS: {
+    /** Stable anonymous install id (uuid, created on first run). */
+    readonly machineId: "~/.sapiom/harness/machine-id";
+    /** Session registry — HarnessSession[] as JSON. */
+    readonly sessions: "~/.sapiom/harness/sessions.json";
+    /** Workflow registry — WorkflowInfo[] as JSON. */
+    readonly workflows: "~/.sapiom/harness/workflows.json";
+    /** Local analytics sink (one AnalyticsEvent per line). Always written. */
+    readonly events: "~/.sapiom/harness/events.ndjson";
+    /** User settings (opt-in state, macros overrides). */
+    readonly settings: "~/.sapiom/harness/settings.json";
+    /** Generated per-session agent config (claude settings/mcp-config files). */
+    readonly generated: "~/.sapiom/harness/generated";
+    /** The bundled example project, seeded lazily by POST /api/sample-project
+     *  (the welcome panel's "Run the sample project") — stable so re-running
+     *  the sample reuses the same copy instead of scattering fresh ones. */
+    readonly sampleProject: "~/.sapiom/harness/sample-project";
+};
+/**
+ * Canvas convention: agents write static HTML here, relative to the session
+ * cwd. The server watches this directory and serves it at
+ * `/canvas/<harnessSessionId>/`.
+ */
+export declare const CANVAS_DIR = ".sapiom/canvas";
+export declare const CANVAS_INDEX = ".sapiom/canvas/index.html";
+/**
+ * Deterministic per-workflow renders live here (one `<slug>.html` per
+ * workflow, slugged by `slugForWorkflowPath` in core/canvas-render.ts),
+ * relative to the session cwd. `GET /canvas/:sessionId/` serves the bound
+ * workflow's render from this directory; `index.html` above stays the
+ * agent-authored/custom canvas and is never rewritten by the deterministic
+ * pipeline.
+ */
+export declare const CANVAS_RENDERS_DIR = ".sapiom/canvas/renders";
+/**
+ * Per-workflow enrichment cache lives here (one `<slug>.json` per workflow,
+ * same slug scheme as CANVAS_RENDERS_DIR), relative to the session cwd:
+ * `{ graph, enrichment, sourceFingerprint, enrichedAt }`. A stale
+ * sourceFingerprint keeps the enrichment displayed (with a "stale" chip)
+ * until a re-run replaces it — see core/canvas-enrich.ts.
+ */
+export declare const CANVAS_CACHE_DIR = ".sapiom/canvas/cache";
+/**
+ * Workspace-state convention: the harness mirrors this session's binding,
+ * the full workflow registry, and its own identity here, relative to the
+ * session cwd, so the agent has an always-current, agent-legible answer to
+ * "what am I working on" and "what workflows exist" without asking. Written
+ * on session create, on every `PATCH /api/sessions/:id/workflow`, and
+ * whenever the workflow registry changes (scan/connect) — see
+ * HarnessWorkspaceContext. Kept present (never deleted) even on unbind.
+ */
+export declare const HARNESS_CONTEXT_FILE = ".sapiom/harness-context.json";
+/**
+ * Environment variables passed to hook scripts / child processes.
+ * INGEST_TOKEN is a per-boot secret; /ingest rejects requests without it.
+ */
+export declare const ENV: {
+    readonly ingestUrl: "SAPIOM_HARNESS_INGEST_URL";
+    readonly ingestToken: "SAPIOM_HARNESS_INGEST_TOKEN";
+    readonly sessionId: "SAPIOM_HARNESS_SESSION_ID";
+    readonly collectorUrl: "SAPIOM_COLLECTOR_URL";
+};
+export type HarnessKind = "claude-code" | "codex";
+export type SessionStatus = "starting" | "running" | "exited";
+/** A harness session = one pty running one agent process in one directory. */
+export interface HarnessSession {
+    /** Our id (uuid). */
+    id: string;
+    /** The agent's own session id (Claude session uuid / Codex rollout id), once known. */
+    agentSessionId: string | null;
+    harness: HarnessKind;
+    /** Absolute path of the project directory the agent runs in. */
+    cwd: string;
+    /** Display title (first prompt, or directory basename until known). */
+    title: string;
+    status: SessionStatus;
+    createdAt: string;
+    lastActiveAt: string;
+    /** Exit code when status === "exited". */
+    exitCode?: number | null;
+    /** The workflow (by path) this session is currently bound to, if any. Set
+     *  via `PATCH /api/sessions/:id/workflow`; mirrored into
+     *  HARNESS_CONTEXT_FILE in the session's cwd so the agent can read it. */
+    boundWorkflowPath: string | null;
+    /**
+     * `status === "running"` only means the pty is alive — the agent's TUI
+     * can still be sitting on a blocking prompt (most commonly: "trust this
+     * directory?") that isn't accepting real input yet. `ready` is the
+     * stronger signal: this pty is actually interactive. Reset to `false` on
+     * every fresh spawn (including resume) and only ever set by
+     * `SessionManager.setReady()` — see there for what flips it. Injecting
+     * input (macros, `/sessions/:id/input`) against a not-ready session
+     * queues briefly then fails loudly (`SessionNotReadyError`) rather than
+     * silently writing into a TUI that isn't listening; raw terminal
+     * keystrokes (`write()`) are deliberately never gated on this, since a
+     * human must always be able to answer the blocking prompt themselves.
+     */
+    ready: boolean;
+}
+/** A resumable past session discovered from agent transcripts or our registry. */
+export interface SessionSummary {
+    /** Back-reference to our session when the registry tracked it (source "registry"). */
+    harnessSessionId?: string;
+    agentSessionId: string;
+    harness: HarnessKind;
+    cwd: string;
+    title: string;
+    lastActiveAt: string;
+    source: "registry" | "transcript";
+}
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+export interface SpawnSpec {
+    command: string;
+    args: string[];
+    /** Merged over process.env. Use `null` to unset a variable. */
+    env: Record<string, string | null>;
+    cwd: string;
+}
+export interface LaunchOpts {
+    harnessSessionId: string;
+    cwd: string;
+    /** Absolute path to the generated system-prompt file (profile). */
+    systemPromptFile?: string;
+    /** Absolute path to the generated MCP config file. */
+    mcpConfigFile?: string;
+    /** Absolute path to the generated settings file (hooks). Claude only. */
+    settingsFile?: string;
+    /** Only consulted by `launchTask` — the one-shot prompt a headless
+     *  background task runs, then exits. Unused by `launch`/`resume`. */
+    prompt?: string;
+    /** Only consulted by `launchTask` — model override (`--model`), e.g.
+     *  "sonnet". Interactive sessions keep the user's own default. */
+    model?: string;
+    /** Only consulted by `launchTask` — hard cap on agent turns
+     *  (`--max-turns`), so a bounded task can't run away. */
+    maxTurns?: number;
+}
+/**
+ * One implementation per supported coding agent. Implementations must be
+ * side-effect free until `launch`/`resume` specs are actually spawned.
+ */
+export interface HarnessAdapter {
+    id: HarnessKind;
+    /** Binary present, version acceptable. */
+    doctor(): Promise<DoctorCheck[]>;
+    launch(opts: LaunchOpts): SpawnSpec;
+    resume(agentSessionId: string, opts: LaunchOpts): SpawnSpec;
+    /** How analytics events are sourced for this harness. */
+    eventSource: "hooks" | "transcript-tail";
+    /** Resumable sessions for a directory (agent-side history). */
+    listPastSessions(cwd: string): Promise<SessionSummary[]>;
+    /**
+     * Best-effort scrollback check for this harness's own known blocking
+     * prompts (e.g. "trust this directory?"), for harnesses whose real
+     * readiness signal (SessionStart-equivalent) can't be trusted to arrive
+     * before the very first input is worth injecting — see CodexAdapter's
+     * implementation for why. Optional: a harness whose readiness signal IS
+     * trustworthy standalone (Claude Code's SessionStart hook) should leave
+     * this unimplemented rather than have SessionManager fall back to a
+     * scrollback heuristic it doesn't need.
+     */
+    detectBlockingPrompt?(scrollback: string): boolean;
+    /**
+     * Builds a one-shot, headless invocation for `TaskManager.run()`: executes
+     * `opts.prompt` non-interactively and exits on its own when the turn
+     * completes — no pty write to submit it and no trust dialog to wait out
+     * (see ClaudeCodeAdapter's implementation, verified against a real
+     * `claude` binary: `-p` mode fires the same hooks a real session does and
+     * skips the trust prompt entirely). Stdout is expected to be line-oriented
+     * JSON progress events (see core/task-stream.ts). Optional: a harness with
+     * no non-interactive mode simply doesn't support background tasks yet —
+     * TaskManager throws a clear error rather than silently misusing `launch`.
+     */
+    launchTask?(opts: LaunchOpts): SpawnSpec;
+}
+export type BackgroundTaskStatus = "running" | "completed" | "failed";
+/**
+ * One headless agent run (today: canvas enrichment, spawned on bind or by
+ * the visualize macro). Deliberately NOT a HarnessSession: tasks never
+ * appear in the session registry (so no tab, no resume, no ghost-record
+ * reconciliation to worry about) and live only in TaskManager's memory —
+ * the pty-less process exits on its own when its single turn completes.
+ */
+export interface BackgroundTask {
+    /** Our id (uuid). Also used as the task's SAPIOM_HARNESS_SESSION_ID and
+     *  its generated-config dir name (covered by the same retention sweep as
+     *  real sessions — see core/inject/retention.ts). */
+    id: string;
+    /** The macro that spawned it (retry re-runs this id). */
+    macroId: string;
+    /** Display label, e.g. "Visualize". */
+    label: string;
+    /** The interactive session the macro was triggered from — the canvas pane
+     *  showing that session renders this task's live status. */
+    harnessSessionId: string;
+    cwd: string;
+    /** The workflow this task was launched for, when it targets one — the
+     *  canvas pane scopes its activity view to the session's CURRENT binding
+     *  via this, so switching workflows mid-task never bleeds another
+     *  workflow's progress into the pane. Null for workflow-less tasks. */
+    workflowPath: string | null;
+    status: BackgroundTaskStatus;
+    startedAt: string;
+    endedAt: string | null;
+    exitCode: number | null;
+    /** Rolling tail of compact human-readable progress lines derived from the
+     *  task's stream-json stdout (see core/task-stream.ts), oldest first. */
+    statusLines: string[];
+    /** The final result event's text when the task completed successfully —
+     *  the payload a structured task (canvas enrichment) parses. Null while
+     *  running and on failure. */
+    resultText: string | null;
+    /** On failure: the result error / stderr tail worth showing a user. */
+    errorTail: string | null;
+}
+export interface TerminalResizeMessage {
+    type: "resize";
+    cols: number;
+    rows: number;
+}
+export type TerminalControlMessage = TerminalResizeMessage;
+export type BusMessage = {
+    type: "session.status";
+    session: HarnessSession;
+} | {
+    type: "canvas.reload";
+    harnessSessionId: string;
+} | {
+    type: "port.detected";
+    harnessSessionId: string;
+    port: number;
+    url: string;
+} | {
+    type: "workflows.changed";
+}
+/**
+ * Full snapshot of one background task, re-broadcast on every change
+ * (spawn, each new status line, completion/failure). Tasks are rare and
+ * their records small, so snapshot-per-change beats a separate delta
+ * protocol the SPA would have to stitch together after a mid-run mount.
+ */
+ | {
+    type: "task.status";
+    task: BackgroundTask;
+}
+/**
+ * Best-effort "this session's pty just produced output" signal, throttled
+ * server-side to at most once per session per ~2s (see SessionManager's
+ * pty.onData handler) — a lightweight substitute for byte-level streaming
+ * on /ws/events, which only the session with an open /ws/terminal socket
+ * receives. Drives the SPA's per-tab busy pulse for background sessions.
+ */
+ | {
+    type: "session.activity";
+    harnessSessionId: string;
+    at: string;
+};
+export declare const ANALYTICS_SCHEMA_VERSION = 1;
+export type AnalyticsEventType = "session.start" | "prompt.submitted" | "tool.call" | "turn.completed" | "session.end";
+/**
+ * The normalized event — the shape that (with opt-in) is batched to the
+ * remote collector and always appended to events.ndjson locally.
+ * `payload` is deliberately schemaless; it lands in a JSONB column.
+ */
+export interface AnalyticsEvent {
+    eventId: string;
+    /** Per-harnessSessionId monotonic counter from 1 — ordering + loss detection. */
+    seq: number;
+    /** ISO-8601, client clock. Use seq (not ts) for intra-session ordering. */
+    ts: string;
+    /** Sapiom user id from auth; null when not logged in. */
+    userId: string | null;
+    /** Sapiom tenant id from auth; null when not logged in. */
+    tenantId: string | null;
+    machineId: string;
+    harnessSessionId: string;
+    agentSessionId: string | null;
+    harness: HarnessKind;
+    type: AnalyticsEventType;
+    payload: Record<string, unknown>;
+}
+/** Static per-install/boot context, sent at batch level. */
+export interface CollectorContext {
+    harnessVersion: string;
+    os: string;
+    arch: string;
+    nodeVersion: string;
+    /** Best-effort agent binary versions, e.g. { "claude-code": "2.0.1" }. */
+    agentVersions?: Record<string, string>;
+}
+/**
+ * Batch POSTed to `${SAPIOM_COLLECTOR_URL}/v1/harness/events`.
+ * Delivery is at-least-once (3 retries then drop): consumers dedupe on
+ * eventId and detect loss via seq gaps. 2xx = accepted; 4xx = drop; 5xx = retry.
+ */
+export interface CollectorBatch {
+    batchId: string;
+    schemaVersion: typeof ANALYTICS_SCHEMA_VERSION;
+    machineId: string;
+    sentAt: string;
+    context: CollectorContext;
+    events: AnalyticsEvent[];
+}
+export interface CreateSessionRequest {
+    cwd: string;
+    harness: HarnessKind;
+    /** Profile id; omit for default. */
+    profile?: string;
+}
+/** Inject text into the session pty (used by macros and the Visualize button). */
+export interface InjectInputRequest {
+    text: string;
+    /** Append a carriage return (submit). Default true. */
+    submit?: boolean;
+}
+/** `PATCH /api/sessions/:id/workflow` body. `null` unbinds. `workflowPath`
+ *  must be a path already known to the workflow registry (scan/connect). */
+export interface BindWorkflowRequest {
+    workflowPath: string | null;
+}
+/** The trimmed workflow shape embedded in HarnessWorkspaceContext — just
+ *  enough for an agent to identify a workflow, not the full WorkflowInfo
+ *  (e.g. `source` is registry bookkeeping the agent has no use for). */
+export interface HarnessWorkspaceContextWorkflow {
+    name: string;
+    path: string;
+    definitionId: number | null;
+}
+/**
+ * The shape written to HARNESS_CONTEXT_FILE in a session's cwd. Schemaless
+ * by convention elsewhere in the harness, but this one file IS a contract —
+ * the default system prompt tells the agent to read it, so its shape is
+ * fixed here like any other REST payload. Deliberately small and
+ * stable-ordered (`workflows` sorted by path) so an agent can diff it
+ * cheaply across reads rather than re-parsing a growing blob.
+ */
+export interface HarnessWorkspaceContext {
+    boundWorkflow: HarnessWorkspaceContextWorkflow | null;
+    /** Every workflow currently known to this harness instance's registry,
+     *  selected or not — lets an agent answer "what workflows exist" without
+     *  a UI action, not just "which one is selected." */
+    workflows: HarnessWorkspaceContextWorkflow[];
+    session: {
+        id: string;
+        cwd: string;
+        harness: HarnessKind;
+    };
+    updatedAt: string;
+}
+export interface AppState {
+    version: string;
+    authenticated: boolean;
+    userId: string | null;
+    organizationName: string | null;
+    telemetryOptIn: boolean;
+    sessions: HarnessSession[];
+    workflows: WorkflowInfo[];
+    macros: MacroDef[];
+    /** The directory the CLI was launched against — the SPA prefills the
+     *  new-session modal with this instead of recentDirs[0]. */
+    launchDir: string;
+    /** Harness kinds with a working binary on PATH at CLI boot (from doctor()),
+     *  in default-preference order — `[0]` is what the auto-created boot
+     *  session used. Optional: omitted by callers that construct AppState
+     *  without running doctor (tests, mocks); the SPA should treat a missing
+     *  value as "assume claude-code is available" until it's wired up. */
+    availableHarnesses?: HarnessKind[];
+    /** Background tasks known to this server boot (running + recent), so a
+     *  page load mid-run shows the canvas activity state immediately instead
+     *  of waiting for the next task.status frame. Optional: omitted by callers
+     *  without a TaskManager (tests, mocks). */
+    tasks?: BackgroundTask[];
+    /** True when this boot found no prior harness use on this machine (no
+     *  recent directories recorded before this launch). Computed once by the
+     *  CLI *before* it records the launch dir / auto-creates the boot session,
+     *  and constant for the server's lifetime — the SPA combines it with "no
+     *  live sessions" to show the first-run welcome panel instead of a bare
+     *  terminal. Optional so AppState constructed without the CLI (tests,
+     *  mocks) reads as a returning user by default. */
+    firstRun?: boolean;
+}
+/** `POST /api/sample-project` response — the seeded (or reused) example. */
+export interface SampleProjectSeedResponse {
+    /** Directory to open a session in — contains the project + its canvas. */
+    root: string;
+    /** Absolute path of the scaffolded example project inside `root`. */
+    projectDir: string;
+    /** False when an already-seeded copy was reused as-is. */
+    created: boolean;
+}
+export interface HarnessSettings {
+    telemetryOptIn: boolean;
+    /** Most-recently-used project directories, newest first. */
+    recentDirs: string[];
+}
+export interface FsDirEntry {
+    name: string;
+    path: string;
+}
+/**
+ * GET /api/fs/list?path= response — directories only, one level deep.
+ * `parent` is always a real path, never null: at the filesystem root it
+ * equals `path` itself (matches `path.dirname("/") === "/"`), so "no
+ * further up" is `parent === path`.
+ */
+export interface FsListResponse {
+    path: string;
+    parent: string;
+    dirs: FsDirEntry[];
+}
+/** An orchestration project on disk, identified by its sapiom.json marker. */
+export interface WorkflowInfo {
+    /** Directory name (or package.json name when present). */
+    name: string;
+    /** Absolute path to the project directory (contains sapiom.json). */
+    path: string;
+    /** From sapiom.json once linked; null before first link. */
+    definitionId: number | null;
+    /** How it entered the registry. */
+    source: "scan" | "connect";
+}
+/**
+ * A macro injects text into the active session's pty, opens a URL, or (the
+ * one exception to "always goes through the agent's session") runs the
+ * deterministic canvas render + AI enrichment refresh server-side. Template
+ * placeholders, substituted server-side before "inject"/"open-url" execution:
+ *   {{workflow.path}} {{workflow.name}} {{workflow.definitionId}}
+ *   {{session.cwd}}   {{canvas.path}}   {{subject}}
+ */
+export interface MacroDef {
+    id: string;
+    label: string;
+    /** Lucide icon name rendered in the rail. */
+    icon: string;
+    action: {
+        kind: "inject";
+        text: string;
+        submit?: boolean;
+    } | {
+        kind: "open-url";
+        url: string;
+    }
+    /** Force refresh of the bound workflow's canvas: invalidates the
+     *  extraction + enrichment caches, re-renders the deterministic diagram
+     *  instantly, and re-spawns the bounded AI enrichment task (see
+     *  core/canvas-enrich.ts) — no pty involved. A cheap no-op when the
+     *  session is unbound. */
+     | {
+        kind: "render-canvas";
+    };
+    /** Macro requires a selected workflow to be enabled. */
+    requiresWorkflow?: boolean;
+    /**
+     * Where an `"inject"` macro's resolved text runs. Default (omitted /
+     * `"inject"`): written into the user's own active session pty, visible in
+     * their terminal and occupying their thread — same as always.
+     * `"background"`: run headless in a one-shot task process via
+     * TaskManager (the user's session is never touched), so a long-running
+     * macro can't interrupt whatever the user was doing.
+     * Ignored for non-"inject" actions.
+     */
+    execution?: "inject" | "background";
+}
+export interface RunMacroRequest {
+    harnessSessionId: string;
+    /** Selected workflow path, when the macro requires one. */
+    workflowPath?: string;
+    /** Free-text subject for the visualize macro. */
+    subject?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

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

package/dist/shared/types.js

@@ -0,0 +1,80 @@
+/**
+ * Sapiom Harness — shared interface contract.
+ *
+ * Every workstream (terminal core, SPA, analytics, CLI, canvas) builds against
+ * the types in this file. Change them only by agreement — this file is the
+ * integration boundary.
+ */
+// ---------------------------------------------------------------------------
+// Constants & well-known paths
+// ---------------------------------------------------------------------------
+export const DEFAULT_PORT = 4100;
+/** All harness-owned state lives under this directory. Uninstall = delete it. */
+export const HARNESS_HOME = "~/.sapiom/harness";
+export const HARNESS_PATHS = {
+    /** Stable anonymous install id (uuid, created on first run). */
+    machineId: `${HARNESS_HOME}/machine-id`,
+    /** Session registry — HarnessSession[] as JSON. */
+    sessions: `${HARNESS_HOME}/sessions.json`,
+    /** Workflow registry — WorkflowInfo[] as JSON. */
+    workflows: `${HARNESS_HOME}/workflows.json`,
+    /** Local analytics sink (one AnalyticsEvent per line). Always written. */
+    events: `${HARNESS_HOME}/events.ndjson`,
+    /** User settings (opt-in state, macros overrides). */
+    settings: `${HARNESS_HOME}/settings.json`,
+    /** Generated per-session agent config (claude settings/mcp-config files). */
+    generated: `${HARNESS_HOME}/generated`,
+    /** The bundled example project, seeded lazily by POST /api/sample-project
+     *  (the welcome panel's "Run the sample project") — stable so re-running
+     *  the sample reuses the same copy instead of scattering fresh ones. */
+    sampleProject: `${HARNESS_HOME}/sample-project`,
+};
+/**
+ * Canvas convention: agents write static HTML here, relative to the session
+ * cwd. The server watches this directory and serves it at
+ * `/canvas/<harnessSessionId>/`.
+ */
+export const CANVAS_DIR = ".sapiom/canvas";
+export const CANVAS_INDEX = `${CANVAS_DIR}/index.html`;
+/**
+ * Deterministic per-workflow renders live here (one `<slug>.html` per
+ * workflow, slugged by `slugForWorkflowPath` in core/canvas-render.ts),
+ * relative to the session cwd. `GET /canvas/:sessionId/` serves the bound
+ * workflow's render from this directory; `index.html` above stays the
+ * agent-authored/custom canvas and is never rewritten by the deterministic
+ * pipeline.
+ */
+export const CANVAS_RENDERS_DIR = `${CANVAS_DIR}/renders`;
+/**
+ * Per-workflow enrichment cache lives here (one `<slug>.json` per workflow,
+ * same slug scheme as CANVAS_RENDERS_DIR), relative to the session cwd:
+ * `{ graph, enrichment, sourceFingerprint, enrichedAt }`. A stale
+ * sourceFingerprint keeps the enrichment displayed (with a "stale" chip)
+ * until a re-run replaces it — see core/canvas-enrich.ts.
+ */
+export const CANVAS_CACHE_DIR = `${CANVAS_DIR}/cache`;
+/**
+ * Workspace-state convention: the harness mirrors this session's binding,
+ * the full workflow registry, and its own identity here, relative to the
+ * session cwd, so the agent has an always-current, agent-legible answer to
+ * "what am I working on" and "what workflows exist" without asking. Written
+ * on session create, on every `PATCH /api/sessions/:id/workflow`, and
+ * whenever the workflow registry changes (scan/connect) — see
+ * HarnessWorkspaceContext. Kept present (never deleted) even on unbind.
+ */
+export const HARNESS_CONTEXT_FILE = ".sapiom/harness-context.json";
+/**
+ * Environment variables passed to hook scripts / child processes.
+ * INGEST_TOKEN is a per-boot secret; /ingest rejects requests without it.
+ */
+export const ENV = {
+    ingestUrl: "SAPIOM_HARNESS_INGEST_URL",
+    ingestToken: "SAPIOM_HARNESS_INGEST_TOKEN",
+    sessionId: "SAPIOM_HARNESS_SESSION_ID",
+    collectorUrl: "SAPIOM_COLLECTOR_URL",
+};
+// ---------------------------------------------------------------------------
+// Analytics events
+// ---------------------------------------------------------------------------
+export const ANALYTICS_SCHEMA_VERSION = 1;
+//# sourceMappingURL=types.js.map

package/dist/shared/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC;AAEjC,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAEhD,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,gEAAgE;IAChE,SAAS,EAAE,GAAG,YAAY,aAAa;IACvC,mDAAmD;IACnD,QAAQ,EAAE,GAAG,YAAY,gBAAgB;IACzC,kDAAkD;IAClD,SAAS,EAAE,GAAG,YAAY,iBAAiB;IAC3C,0EAA0E;IAC1E,MAAM,EAAE,GAAG,YAAY,gBAAgB;IACvC,sDAAsD;IACtD,QAAQ,EAAE,GAAG,YAAY,gBAAgB;IACzC,6EAA6E;IAC7E,SAAS,EAAE,GAAG,YAAY,YAAY;IACtC;;4EAEwE;IACxE,aAAa,EAAE,GAAG,YAAY,iBAAiB;CACvC,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,gBAAgB,CAAC;AAC3C,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,UAAU,aAAa,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,UAAU,UAAU,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,UAAU,QAAQ,CAAC;AAEtD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,8BAA8B,CAAC;AAEnE;;;GAGG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,SAAS,EAAE,2BAA2B;IACtC,WAAW,EAAE,6BAA6B;IAC1C,SAAS,EAAE,2BAA2B;IACtC,YAAY,EAAE,sBAAsB;CAC5B,CAAC;AA8NX,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC"}