clinkx 0.2.3 → 1.0.0

package/clinkx-workflows/dist/config.d.ts

@@ -10,47 +10,78 @@
  * REAL controls (child env CAN control these):
  * - CLINKX_MAX_CONCURRENT: fail-fast semaphore depth (concurrency.ts:3,25-29)
  * - CLINKX_MAX_RESPONSE_CHARS: output truncation ceiling (pipeline.ts env fallback)
- * - CLINKX_MAX_OUTPUT_BYTES: per-stream capture cap (runner.ts::createStreamCapture)
+ * - CLINKX_MAX_OUTPUT_BYTES: per-stream capture cap — legacy fallback read only when
+ *   CLINKX_MAX_CAPTURE_BYTES is unset (runner.ts capture resolution). Effective in the
+ *   child because the scrub removes CLINKX_MAX_CAPTURE_BYTES and re-injection never sets it.
  * - CLINKX_MAX_PROMPT_BYTES: pre-dispatch prompt ceiling (runner.ts)
  * - CLINKX_CONFIG_PATH: adapter config path override
  * - CLINKX_ALLOWED_ROOTS: comma-separated allowed path prefixes
  * - CLINKX_LOG_LEVEL: pino log verbosity
  *
  * DEAD knobs (adapter JSON wins, env has no effect with current shipped adapters):
- * - CLINKX_TIMEOUT_SECONDS: both shipped adapters set timeout_seconds in JSON
- *   (codex.json:9 = 3600, claude.json:8 = 3600). Adapter config wins per runner.ts:156-159.
- * - CLINKX_IDLE_TIMEOUT_SECONDS: both shipped adapters set idle_timeout_seconds in JSON.
- *   Adapter config wins per runner.ts:164-167.
- * - CLINKX_IDLE_TIMEOUT_STARTUP_SECONDS: both shipped adapters set idle_timeout_startup_seconds.
- *   Adapter config wins per runner.ts:168-171. Additionally, result_contract.enabled forces
- *   both idle timers to 0 (runner.ts:163-170).
+ * - CLINKX_TIMEOUT_SECONDS: every shipped subprocess adapter (conf/adapters/*.json and
+ *   conf/adapters/hapi/*.json) sets timeout_seconds = 3600 in JSON. Adapter config wins
+ *   per the runner.ts timeout resolution (options > adapter > env > default).
+ * - CLINKX_IDLE_TIMEOUT_SECONDS: every shipped subprocess adapter sets
+ *   idle_timeout_seconds in JSON. Adapter config wins (same precedence).
+ * - CLINKX_IDLE_TIMEOUT_STARTUP_SECONDS: every shipped subprocess adapter sets
+ *   idle_timeout_startup_seconds. Adapter config wins (same precedence). Additionally,
+ *   an adapter with suppress_stdout and no stderr_to_file has both idle timers forced
+ *   to 0 — no observable byte channel (runner.ts idle resolution).
  */
+import type { WorkflowContextRequestedMode } from "./context-mode-resolver.js";
+export declare const DEFAULT_DASHBOARD_MAX_STATE_BYTES = 16777216;
+export declare const MIN_DASHBOARD_MAX_STATE_BYTES = 1048576;
+export declare const MAX_DASHBOARD_MAX_STATE_BYTES = 67108864;
 export declare const DEFAULT_RETAIN_FAILED_DAYS = 30;
 export declare const DEFAULT_RETAIN_CANCELLED_DAYS = 30;
 export declare const DEFAULT_RETAIN_DEBUG_DAYS = 7;
+export declare const DEFAULT_RETAIN_ASYNC_DAYS = 1;
+export declare const DEFAULT_RETAIN_SUCCEEDED_DAYS = 1;
+export declare const DEFAULT_DASHBOARD_PORT = 4180;
 export interface RetentionConfig {
     readonly retainFailedDays: number;
     readonly retainCancelledDays: number;
     readonly retainDebugDays: number;
+    readonly retainAsyncDays: number;
+    readonly retainSucceededDays: number;
 }
-/** Resolve workspace root: explicit env > process.cwd() with warning. */
+/** Resolve workspace root: explicit env > process.cwd() fallback (callers warn at startup). */
 export declare function resolveWorkspaceRoot(): string;
 /** Whether workspace root was explicitly configured. */
 export declare function hasExplicitWorkspaceRoot(): boolean;
 /**
- * Derive CLINKX_ALLOWED_ROOTS for the child process.
- * Union of resolved workspace root + workflow state/artifact roots.
- * Rejects filesystem root (/) as workspace root.
+ * Derive CLINKX_ALLOWED_ROOTS for the child process: the resolved workspace
+ * root plus the workflow state/artifact roots, comma-joined. The state and
+ * artifact roots carry the artifact-only `/.` marker (artifactOnlyEnvEntry),
+ * so the child may use them for artifact/state I/O but context_builder never
+ * admits them as source roots.
+ *
+ * Performs NO validation of workspaceRoot: a cwd-derived root (see
+ * resolveWorkspaceRoot's fallback) is passed through as-is — including "/",
+ * which grants the child filesystem-wide reach. The only guardrail today is
+ * the startup warning both servers emit when CLINKX_WORKFLOWS_WORKSPACE_ROOT
+ * is unset.
  */
 export declare function deriveAllowedRoots(workspaceRoot: string, stateDir: string, artifactsDir: string): string;
 /** Command to spawn the owned ClinkX child. */
 export declare function getClinkxCmd(): string;
 /** Workflow definition directory. */
 export declare function getWorkflowsPath(): string;
+/** Effective absolute workflow definition directory used by the loader. */
+export declare function getResolvedWorkflowsPath(): string;
+/** Soft default for workflow context-builder preflight mode. */
+export declare function getWorkflowsContextDefault(): WorkflowContextRequestedMode;
+/** Curator adapter name used by the injected default full delegate. */
+export declare function getWorkflowsContextDefaultCurator(): string;
 /** Prompt template root directory (resolved relative to package root). */
 export declare function getTemplatesPath(): string;
 /** Upper bound for concurrent calls within a parallel stage. */
 export declare function getMaxParallel(): number;
+/** Process-wide cap for detached workflow runs (integer-strict, >= 1). */
+export declare function getWorkflowsMaxConcurrentAsync(): number;
+/** Override that allows raw async admission above the context-builder pool cap. */
+export declare function getWorkflowsAllowUnsafeAsyncCap(): boolean;
 /** Passed to child as CLINKX_MAX_CONCURRENT. */
 export declare function getChildMaxConcurrent(): number;
 /** Passed to child as CLINKX_MAX_RESPONSE_CHARS (200k to avoid silent context truncation). */
@@ -61,6 +92,99 @@ export declare function getChildMaxOutputBytes(): number;
 export declare function getChildMaxPromptBytes(): number;
 /** Optional workflow-owned child adapter bundle path. */
 export declare function getChildConfigPath(): string | undefined;
+/** Loopback HTTP port for the standalone dashboard. */
+export declare function getDashboardPort(): number;
+/** Maximum admitted dashboard state.json byte count. */
+export declare function getDashboardMaxStateBytes(): number;
+export declare const DASHBOARD_PUBLIC_API_ORIGIN_ENV = "CLINKX_WORKFLOWS_DASHBOARD_PUBLIC_API_ORIGIN";
+export declare const DASHBOARD_UI_ORIGIN_ENV = "CLINKX_WORKFLOWS_DASHBOARD_UI_ORIGIN";
+export declare const DASHBOARD_AUTH_MODE_ENV = "CLINKX_WORKFLOWS_DASHBOARD_AUTH_MODE";
+export declare const DASHBOARD_CREDENTIAL_DIR_ENV = "CLINKX_WORKFLOWS_DASHBOARD_CREDENTIAL_DIR";
+export declare const DASHBOARD_RP_NAME_ENV = "CLINKX_WORKFLOWS_DASHBOARD_RP_NAME";
+export declare const DASHBOARD_SESSION_TTL_SECONDS_ENV = "CLINKX_WORKFLOWS_DASHBOARD_SESSION_TTL_SECONDS";
+export declare const DEFAULT_DASHBOARD_RP_NAME = "ClinkX Dashboard";
+export declare const DEFAULT_DASHBOARD_SESSION_TTL_SECONDS = 43200;
+export interface CanonicalHttpsOrigin {
+    /**
+     * Canonical origin serialization, e.g. `https://dash.example.com` — always
+     * https, no trailing slash, no default `:443`, no credentials/path/query/
+     * fragment.
+     */
+    readonly origin: string;
+    /**
+     * Host authority including any non-default port, e.g. `dash.example.com` or
+     * `dash.example.com:8443`. Suitable for an exact `Host` comparison.
+     */
+    readonly host: string;
+}
+/**
+ * Reusable canonical absolute-HTTPS origin parser. Accepts only the exact
+ * canonical origin serialization and rejects everything else fail-closed:
+ * non-https, embedded credentials, any path beyond root, query, fragment,
+ * wildcard, comma list, whitespace, and any non-canonical serialization
+ * (trailing slash, default `:443`, uppercase host, IDN not already punycoded).
+ *
+ * `label` is embedded in the thrown message so callers surface an actionable
+ * startup error naming the offending variable.
+ */
+export declare function parseCanonicalHttpsOrigin(raw: string, label: string): CanonicalHttpsOrigin;
+export type DashboardPublicAccess = Readonly<{
+    mode: "local";
+}> | Readonly<{
+    mode: "remote";
+    /** Canonical HTTPS origin the SPA calls for `/api/*`. */
+    publicApiOrigin: string;
+    /** Canonical HTTPS origin the static UI is served from. */
+    uiOrigin: string;
+    /** Public `Host` authority derived from the API origin. */
+    publicHost: string;
+}>;
+export type DashboardAuthMode = "passkey" | "bearer";
+export interface DashboardAuthConfig {
+    readonly rpName: string;
+    readonly expectedOrigin: string;
+    readonly expectedRPID: string;
+    readonly expectedHost: string;
+    readonly secureCookies: boolean;
+    readonly credentialDirectory: string;
+    readonly sessionTtlSeconds: number;
+}
+export interface DashboardAuthConfigInput {
+    readonly publicAccess: DashboardPublicAccess;
+    readonly localPort?: number;
+    readonly credentialDirectory: string;
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve the passkey credential directory independently from workflow state.
+ * Explicit values are intentionally not trimmed or normalized.
+ */
+export declare function resolveDashboardCredentialDirectory(env?: NodeJS.ProcessEnv, stateDirectory?: string): string;
+/** Resolve the temporary passkey/bearer rollback selector. */
+export declare function resolveDashboardAuthMode(env?: NodeJS.ProcessEnv): DashboardAuthMode;
+/**
+ * Derive the complete WebAuthn configuration from the public dashboard origin.
+ * The caller supplies the active local port only after the first loopback
+ * listener has selected it; cloud inputs are validated before listener or
+ * filesystem work.
+ */
+export declare function resolveDashboardAuthConfig(input: DashboardAuthConfigInput): DashboardAuthConfig;
+/**
+ * Resolve the discriminated local/remote dashboard access value from the strict
+ * env pair. Both absent → local; exactly one present → actionable startup
+ * error; both present → remote (each origin parsed canonically). The returned
+ * value carries no bearer/tunnel credentials.
+ */
+export declare function resolveDashboardPublicAccess(env?: NodeJS.ProcessEnv): DashboardPublicAccess;
+/**
+ * Build the remote static-deployment Content-Security-Policy. Identical to the
+ * loopback dashboard CSP except `connect-src` adds the exact API origin (only
+ * `'self'` plus that origin — never a wildcard or credentials). The origin is
+ * re-parsed defensively so a malformed value can never be injected into the
+ * header. Kept here as the single source of truth mirrored by the buildless
+ * static runtime under `deploy/dashboard-ui/serve.mjs`.
+ */
+export declare function dashboardStaticCsp(publicApiOrigin: string): string;
 /**
  * Default workflow-level timeout (seconds).
  *
@@ -84,7 +208,7 @@ export declare function getLogLevel(): string;
 /** Age-based retention thresholds for persisted workflow run directories. */
 export declare function getRetentionConfig(): RetentionConfig;
 /** Persistent workflow state directory. */
-export declare function getStateDir(): string;
+export declare function getStateDir(env?: NodeJS.ProcessEnv, accountHomeProvider?: () => string): string;
 /** Base directory containing persistent run state directories. */
 export declare function getRunsDir(): string;
 /** Persistent state directory for a specific run. */
@@ -104,6 +228,8 @@ export declare const CHILD_ENV_SCRUB_EXTRA: readonly ["XDG_CONFIG_HOME"];
 /**
  * Child env vars that are re-injected with workflow-owned values.
  * Maps from workflow config key to child env var name.
+ * Reference only: buildChildEnv (child-env.ts) performs the re-injection with
+ * explicit assignments and does not read this map. Keep the two in sync.
  */
 export declare const CHILD_ENV_REINJECT_MAP: {
     readonly maxConcurrent: "CLINKX_MAX_CONCURRENT";
@@ -115,14 +241,17 @@ export declare const CHILD_ENV_REINJECT_MAP: {
     readonly logLevel: "CLINKX_LOG_LEVEL";
 };
 /**
- * Baseline OS env vars that are NEVER scrubbed from child.
+ * Baseline OS env vars that are never scrubbed from the child.
+ * Reference only: buildChildEnv does not read this list — these vars survive
+ * because the scrub removes only CLINKX_* and CHILD_ENV_SCRUB_EXTRA.
  * ClinkX's internal env.ts::buildEnv handles delegate subprocess sanitization.
  */
 export declare const CHILD_ENV_BASELINE: readonly ["PATH", "HOME", "USER", "LANG", "TMPDIR"];
 /**
  * DEAD KNOBS: these env vars have no effect with current shipped adapters
- * because adapter JSON config wins (runner.ts:156-171). Both shipped adapters
- * set timeout_seconds in JSON (codex.json:9 = 3600, claude.json:8 = 3600).
+ * because adapter JSON config wins (runner.ts timeout/idle resolution:
+ * options > adapter > env > default). Every shipped subprocess adapter sets
+ * timeout_seconds = 3600 in JSON.
  *
  * These are Layer 3 (child-side) timeout controls. The workflow engine does
  * NOT attempt to control child-side timeouts via env vars. Instead, use