antpath 0.3.1 → 0.4.1

package/README.md

@@ -16,24 +16,26 @@ import {
 ```
 
 ```bash
-antpath run ./template.json --api-token ant_… --workspace … --dashboard-url … \
+antpath run ./template.json --api-token ant_… \
   --anthropic-api-key sk-ant-… --follow
-antpath status   <run-id> --api-token … --workspace … --dashboard-url …
-antpath events   <run-id> --api-token … --workspace … --dashboard-url … --follow
-antpath outputs  <run-id> --api-token … --workspace … --dashboard-url …
-antpath download <run-id> <output-id> --out ./local --api-token … --workspace … --dashboard-url …
-antpath cancel   <run-id> --api-token … --workspace … --dashboard-url …
-antpath delete   <run-id> --api-token … --workspace … --dashboard-url …
-antpath whoami            --api-token … --dashboard-url …
+antpath status   <run-id> --api-token …
+antpath events   <run-id> --api-token … --follow
+antpath outputs  <run-id> --api-token …
+antpath download <run-id> <output-id> --out ./local --api-token …
+antpath cancel   <run-id> --api-token …
+antpath delete   <run-id> --api-token …
+antpath whoami            --api-token …
 ```
 
 The SDK class and the CLI are backed by the same `@antpath/shared` operations module — any read or write you can do through one, you can do through the other, against the same durable run records. The same npm package also ships the in-container `antpath` CLI as its `bin` entry; the worker mounts that CLI at `/antpath/antpath` inside every run so skills can call `antpath proxy …` against the per-run manifest. See [Agent-first surface design](../../references/development-principles.md#agent-first-surface-design).
 
+The dashboard URL defaults to `https://antpath.ai`. Self-hosted deployments override with `--dashboard-url` on the CLI or `baseUrl` on `AntpathClient`. The workspace is derived server-side from your API token (1:1 binding), so there is no `--workspace` flag and no `workspaceId` option.
+
 ## MVP boundaries
 
 - Claude Managed Agents only.
 - BYO Anthropic key + MCP credentials + skill references — passed inline on every submission, vaulted for the lifetime of a single run, destroyed at cleanup.
-- Workspace is the tenant boundary. Every operation is scoped to the workspace bound at client construction.
+- Workspace is the tenant boundary. Workspace identity is derived server-side from the API token (1:1 binding); the SDK / CLI never name it.
 - No SDK-side storage of provider keys, MCP credentials, or output file contents.
 - Cleanup runs by default; opt into retention with `cleanup.session: "retain"`.
 
@@ -43,9 +45,8 @@ The SDK class and the CLI are backed by the same `@antpath/shared` operations mo
 import { AntpathClient, defineTemplate, string } from "antpath";
 
 const client = new AntpathClient({
-  baseUrl: "https://antpath.example.com",
-  apiToken: process.env.ANTPATH_API_TOKEN!,
-  workspaceId: process.env.ANTPATH_WORKSPACE_ID!
+  apiToken: process.env.ANTPATH_API_TOKEN!
+  // baseUrl defaults to https://antpath.ai — set it for self-hosted deployments.
 });
 
 const template = defineTemplate({
@@ -84,8 +85,6 @@ The same flow from the CLI:
 ```bash
 antpath run ./template.json \
   --api-token "$ANTPATH_API_TOKEN" \
-  --workspace "$ANTPATH_WORKSPACE_ID" \
-  --dashboard-url https://antpath.example.com \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --var topic="agent-first SDK design" \
   --follow

package/dist/_shared/blueprint.d.ts

@@ -0,0 +1,263 @@
+/**
+ * The flat agent-first composition surface that replaces `Template`.
+ *
+ * Concepts (mirrored in references/architecture-decisions.md):
+ *
+ *   - `SkillRef` is the wire-level reference to a skill — either an
+ *     `skl_*` id pointing at a workspace-uploaded bundle, or a
+ *     `{vendor, skillId, version}` reference to a provider built-in.
+ *     The two shapes are discriminated by `kind` so consumers branch
+ *     mechanically and providers can never accidentally be looked up
+ *     in `skill_bundles`.
+ *
+ *   - `McpServerRef` is the non-secret part of an MCP server declaration:
+ *     `name` and `url`. Bearer / cookie / per-request headers travel in
+ *     the run's vaulted `secrets.mcpServers` block keyed by the same
+ *     `name`, and never enter the hashed submission payload or the
+ *     run snapshot.
+ *
+ *   - `Blueprint` is what the user authors. It excludes
+ *     `secrets`/`idempotencyKey`/`signal` so it can be safely persisted
+ *     to disk (e.g. `antpath run --config run.json`), shared between
+ *     teams, or curried via `defineRun` without leaking credentials.
+ *     Strings inside a Blueprint are **already resolved** — there are
+ *     no `{{variable}}` placeholders, no template language, no late
+ *     binding. The whole point of `defineRun` is to make the resolution
+ *     happen at the TS call site where the IDE can type-check it.
+ *
+ *   - Skill bundle validation lives here so the SDK (zipping locally),
+ *     the BFF (server-side unzip + manifest extraction), and the worker
+ *     (sanity-check before mounting) share a single source of truth for
+ *     the limits, the path normaliser, and the manifest invariants. The
+ *     DB CHECK constraints on `skill_bundles.manifest` mirror these.
+ *
+ * See `references/architecture-decisions.md` (Composition primitives,
+ * Skill custody) and `references/development-principles.md` (Agent-first
+ * surface design) for the rationale.
+ */
+import type { JsonValue, PlatformCleanupPolicy, PlatformProxyEndpoint, PlatformTemplateEnvironment } from "./submission.js";
+/**
+ * Mirrors the CHECK constraint
+ * `skill_bundles_id_format_chk = check (id ~ '^skl_[A-Za-z0-9_-]{8,128}$')`
+ * defined in supabase/migrations/20260512000000_skill_bundles.sql. Keep
+ * the two in lockstep — the DB is the ultimate authority.
+ */
+export declare const SKILL_ID_PATTERN: RegExp;
+/**
+ * Human-readable, workspace-scoped name. Lowercase, kebab-friendly,
+ * 1..128 chars. The DB enforces the length bound via
+ * `skill_bundles_name_len_chk`; this regex tightens the SDK/CLI input
+ * surface so callers fail at the boundary rather than in the BFF.
+ */
+export declare const SKILL_NAME_PATTERN: RegExp;
+/**
+ * Hard caps applied at upload time. The SDK enforces these before
+ * computing the zip hash so a clearly-too-big bundle never wastes
+ * bytes-on-the-wire; the BFF re-enforces server-side because the SDK
+ * is untrusted. Numbers are deliberately conservative for the MVP and
+ * can be tuned later; keep this object as the single tuning point.
+ */
+export declare const SKILL_BUNDLE_LIMITS: {
+    /** Compressed (.zip) ceiling. */
+    readonly maxCompressedBytes: number;
+    /** Sum of uncompressed file sizes. */
+    readonly maxDecompressedBytes: number;
+    /** Number of regular file entries (directories don't count). */
+    readonly maxFiles: 1000;
+    /** Maximum directory nesting depth — `a/b/c/d` has depth 4. */
+    readonly maxDepth: 16;
+    /** Single-entry path length cap. */
+    readonly maxPathLength: 512;
+    /** Stored file mode for ordinary files. */
+    readonly defaultFileMode: 420;
+    /** Stored directory mode. */
+    readonly defaultDirMode: 493;
+};
+export type SkillRef = WorkspaceSkillRef | ProviderSkillRef;
+export interface WorkspaceSkillRef {
+    readonly kind: "workspace";
+    readonly id: string;
+}
+export interface ProviderSkillRef {
+    readonly kind: "provider";
+    readonly vendor: "anthropic" | "custom";
+    readonly skillId: string;
+    readonly version?: string;
+}
+export declare function isWorkspaceSkillRef(ref: SkillRef): ref is WorkspaceSkillRef;
+export declare function isProviderSkillRef(ref: SkillRef): ref is ProviderSkillRef;
+/**
+ * Parse a `SkillRef` from untrusted input. Used by the BFF run parser
+ * and by the operations module when deserialising API responses. Throws
+ * with a precise path so the caller can surface a usable error.
+ */
+export declare function parseSkillRef(input: unknown, path: string): SkillRef;
+/**
+ * Manifest entry persisted in `skill_bundles.manifest` and
+ * `run_skill_snapshots.manifest`. `path` is forward-slash, relative,
+ * normalised. `mode` is the stored POSIX mode (sanitised, NOT the user's
+ * filesystem mode) — see `SKILL_BUNDLE_LIMITS.defaultFileMode`.
+ */
+export interface SkillBundleEntry {
+    readonly path: string;
+    readonly size: number;
+    readonly mode: number;
+}
+export interface SkillBundleManifest {
+    readonly entries: readonly SkillBundleEntry[];
+    /** Total uncompressed bytes (sum of `entries[i].size`). */
+    readonly totalSize: number;
+    /** Number of file entries. Equals `entries.length` by construction. */
+    readonly fileCount: number;
+}
+export declare class SkillBundleValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reject input paths that try to escape the bundle root or smuggle
+ * platform-specific syntax. Returns the canonical forward-slash
+ * relative path; never returns paths starting or ending with `/`.
+ *
+ * Rejects:
+ *   - empty strings and pure whitespace
+ *   - absolute paths (`/foo`, `C:\foo`, `\\server\share`)
+ *   - backslash separators (Windows)
+ *   - `..` segments anywhere in the path
+ *   - `.` segments anywhere except a leading bare `.`
+ *   - paths whose length exceeds `SKILL_BUNDLE_LIMITS.maxPathLength`
+ *   - paths whose depth exceeds `SKILL_BUNDLE_LIMITS.maxDepth`
+ *   - NUL bytes
+ */
+export declare function normaliseSkillBundlePath(input: string): string;
+/**
+ * Validate one manifest entry: normalises the path, bounds the size,
+ * and sanitises the mode to one of {defaultFileMode, defaultDirMode}.
+ * The bundle is files-only, so any non-regular-file entry is rejected
+ * upstream by the caller (zip parser must skip symlinks, device files,
+ * etc. before reaching this function).
+ */
+export declare function validateSkillBundleEntry(input: {
+    readonly path: string;
+    readonly size: number;
+    readonly mode?: number;
+}): SkillBundleEntry;
+/**
+ * Validate a full manifest. Enforces:
+ *   - entries is a non-empty array
+ *   - `SKILL.md` exists at the bundle root (Claude's auto-discovery key)
+ *   - file count <= maxFiles
+ *   - total uncompressed size <= maxDecompressedBytes
+ *   - per-entry validation (see `validateSkillBundleEntry`)
+ *   - no duplicate paths
+ *
+ * Returns a canonical manifest with totals computed.
+ */
+export declare function validateSkillBundleManifest(input: ReadonlyArray<{
+    readonly path: string;
+    readonly size: number;
+    readonly mode?: number;
+}>): SkillBundleManifest;
+/**
+ * The non-secret half of an MCP server declaration. This is what enters
+ * the hashed submission, the run snapshot, and any audit log. `name`
+ * keys into `secrets.mcpServers` for the per-request headers.
+ */
+export interface McpServerRef {
+    readonly name: string;
+    readonly url: string;
+}
+export declare const MCP_SERVER_NAME_PATTERN: RegExp;
+/**
+ * A Blueprint-level MCP entry. The user is free to supply headers
+ * inline; the SDK splits the call site cleanly at submission time so
+ * the Authorization (or other auth-bearing) header never enters the
+ * non-secret wire payload.
+ */
+export interface BlueprintMcpServer extends McpServerRef {
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export declare function parseMcpServerRef(input: unknown, path: string): McpServerRef;
+/**
+ * What the user authors and passes to `client.submitRun({...blueprint, secrets})`.
+ *
+ * Blueprint deliberately EXCLUDES `secrets`, `idempotencyKey`, and
+ * `signal` so:
+ *   - `defineRun((p) => Blueprint)` can be reused across calls without
+ *     re-injecting an API key,
+ *   - a Blueprint can be JSON-serialised to disk (`antpath run --config
+ *     run.json`) without ever encoding a credential,
+ *   - audit / replay tooling can persist a Blueprint as-is.
+ */
+export interface Blueprint {
+    readonly model: string;
+    readonly system?: string;
+    readonly prompt: string | readonly string[];
+    readonly skills?: readonly SkillRef[];
+    readonly mcpServers?: readonly BlueprintMcpServer[];
+    readonly environment?: PlatformTemplateEnvironment;
+    readonly cleanup?: PlatformCleanupPolicy;
+    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+}
+/**
+ * Currier for parameterised Blueprints.
+ *
+ * ```ts
+ * const investigate = defineRun((p: { repo: string; issue: number }) => ({
+ *   model: "claude-sonnet-4-5-20250929",
+ *   system: `You work on ${p.repo}.`,
+ *   prompt: `Investigate issue #${p.issue}.`,
+ *   skills: [rules],
+ * }));
+ * await client.submitRun({
+ *   ...investigate({ repo: "antpath", issue: 123 }),
+ *   secrets: { anthropic: { apiKey } },
+ * });
+ * ```
+ *
+ * The returned function is referentially transparent — it just calls
+ * the provided producer. The wrapper exists for two reasons: (a) a
+ * single named entry point makes IDEs surface the type of the inner
+ * blueprint at the call site, and (b) it pins the "no late binding"
+ * contract — strings inside the Blueprint are resolved by the TS call
+ * site, not by a server-side template engine.
+ */
+export declare function defineRun<TParams>(producer: (params: TParams) => Blueprint): (params: TParams) => Blueprint;
+/**
+ * Parse a Blueprint from JSON. Defensive — used by the host CLI to
+ * load `--config run.json`. Throws with the JSON path that failed so
+ * a user can fix their file. Headers are preserved here and split out
+ * later by the SDK normalisation step.
+ */
+export declare function parseBlueprint(input: unknown): Blueprint;
+/**
+ * Result of splitting a `Blueprint` into the non-secret submission and
+ * the secret MCP-headers bundle. The SDK calls this just before posting
+ * to /api/runs: the `submission` half is what the BFF hashes for
+ * idempotency, the `mcpServerSecrets` half is what enters the Vault.
+ *
+ * `prompt` is normalised to `readonly string[]` (single-string callers
+ * get wrapped in a length-1 array) so the wire payload, the worker, and
+ * the audit log don't have to re-handle two shapes.
+ */
+export interface NormalisedBlueprint {
+    readonly model: string;
+    readonly system?: string;
+    readonly prompt: readonly string[];
+    readonly skills: readonly SkillRef[];
+    readonly mcpServers: readonly McpServerRef[];
+    readonly environment?: PlatformTemplateEnvironment;
+    readonly cleanup?: PlatformCleanupPolicy;
+    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+    /**
+     * MCP servers whose Blueprint entry carried `headers`. Keyed by the
+     * `name` that appears in `mcpServers` so the BFF can pair them up.
+     */
+    readonly mcpServerSecrets: ReadonlyArray<{
+        readonly name: string;
+        readonly url: string;
+        readonly headers: Readonly<Record<string, string>>;
+    }>;
+}
+export declare function normaliseBlueprint(blueprint: Blueprint): NormalisedBlueprint;