@spacefast/common 0.0.6 → 0.0.8

package/dist/contracts/sf-config-v1.d.ts

@@ -0,0 +1,75 @@
+export declare const SF_CONFIG_V1_CANONICAL_FILE = "sf.jsonc";
+export declare const SF_CONFIG_V1_FILES: readonly ["sf.jsonc", "spacefast.jsonc", "spacefast.json", "sf.json", ".sf/sf.json", ".sf/config.jsonc", ".sf/config.json"];
+/** Published JSON Schema URL for the strict `sf.jsonc` v1 contract. */
+export declare const SF_CONFIG_V1_SCHEMA_URL: `${string}/schemas/sf.v1.json`;
+export type SfConfigV1 = {
+    $schema?: typeof SF_CONFIG_V1_SCHEMA_URL;
+    version: 1;
+    build?: {
+        installRoot?: string;
+        installCommand?: string;
+        command?: string;
+        output?: string;
+        timeoutSeconds?: number;
+    };
+    serve?: {
+        index?: string | false;
+        spaFallback?: string;
+        cleanUrls?: boolean;
+        directoryListing?: boolean;
+    };
+    metadata?: {
+        title?: string;
+        description?: string;
+        image?: string;
+    };
+    substitute?: {
+        files: string[];
+    };
+};
+export type EffectiveConfigV1 = {
+    version: 1;
+    build?: NonNullable<SfConfigV1["build"]> & {
+        installRoot: string;
+        timeoutSeconds: number;
+    };
+    serve: {
+        index: string | false;
+        spaFallback?: string;
+        cleanUrls: boolean;
+        directoryListing: boolean;
+    };
+    metadata?: SfConfigV1["metadata"];
+    substitute?: SfConfigV1["substitute"];
+};
+export type SfConfigV1Issue = {
+    code: "config_alias" | "config_conflict" | "config_identity_moved" | "config_invalid" | "config_key_removed" | "config_unknown_key" | "serve_index_required" | "template_syntax_retired";
+    severity: "error" | "warning";
+    path: string;
+    line: number;
+    column: number;
+    message: string;
+    suggestion?: string;
+};
+export type SfConfigV1Location = Pick<SfConfigV1Issue, "line" | "column">;
+type SfConfigV1CompileResultBase = {
+    issues: SfConfigV1Issue[];
+    locations: ReadonlyMap<string, SfConfigV1Location>;
+};
+export type SfConfigV1CompileResult = SfConfigV1CompileResultBase & ({
+    success: true;
+    config: SfConfigV1;
+    effective: EffectiveConfigV1;
+} | {
+    success: false;
+    config: null;
+    effective: null;
+});
+export type CompileSfConfigV1Options = {
+    artifactPaths?: readonly string[];
+    templateSources?: readonly {
+        path: string;
+        source: string;
+    }[];
+};
+export {};

package/dist/contracts/sf-config-v1.js

@@ -0,0 +1,6 @@
+import { BRAND } from "../brand.js";
+import { SPACE_CONFIG_ACCEPTED_FILES, SPACE_CONFIG_CANONICAL_FILE, } from "./space-config.js";
+export const SF_CONFIG_V1_CANONICAL_FILE = SPACE_CONFIG_CANONICAL_FILE;
+export const SF_CONFIG_V1_FILES = SPACE_CONFIG_ACCEPTED_FILES;
+/** Published JSON Schema URL for the strict `sf.jsonc` v1 contract. */
+export const SF_CONFIG_V1_SCHEMA_URL = `${BRAND.websiteOrigin}/schemas/sf.v1.json`;

package/dist/contracts/spaces.d.ts

@@ -189,6 +189,7 @@ export declare const SpaceCreateResponseSchema: z.ZodObject<{
                 noscript: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        settingsDigest: z.ZodString;
         noindex: z.ZodBoolean;
         policy: z.ZodNullable<z.ZodObject<{
             rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -586,6 +587,8 @@ export declare const spacePatchSchema: z.ZodObject<{
             noscript: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
+    baseSettingsDigest: z.ZodOptional<z.ZodString>;
+    force: z.ZodOptional<z.ZodBoolean>;
     dataLocation: z.ZodOptional<z.ZodString>;
     placement: z.ZodOptional<z.ZodObject<{
         region: z.ZodOptional<z.ZodString>;
@@ -756,6 +759,11 @@ export declare const spaceVersionCreateSchema: z.ZodObject<{
     }>>;
     sourceMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     buildLog: z.ZodOptional<z.ZodString>;
+    conventionFiles: z.ZodOptional<z.ZodObject<{
+        redirects: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodString>;
+        routes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     files: z.ZodOptional<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         size: z.ZodNumber;
@@ -1203,6 +1211,7 @@ export declare const spaceListSchema: z.ZodObject<{
                 noscript: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        settingsDigest: z.ZodString;
         noindex: z.ZodBoolean;
         policy: z.ZodNullable<z.ZodObject<{
             rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -2009,11 +2018,11 @@ export declare const spaceVersionComputedRoutingSummarySchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const spaceVersionFileDiffStatusSchema: z.ZodEnum<{
     deleted: "deleted";
+    unchanged: "unchanged";
     binary: "binary";
     added: "added";
     modified: "modified";
     renamed: "renamed";
-    unchanged: "unchanged";
     too_large: "too_large";
 }>;
 export declare const spaceVersionFileDiffEntrySchema: z.ZodObject<{
@@ -2021,11 +2030,11 @@ export declare const spaceVersionFileDiffEntrySchema: z.ZodObject<{
     oldPath: z.ZodNullable<z.ZodString>;
     status: z.ZodEnum<{
         deleted: "deleted";
+        unchanged: "unchanged";
         binary: "binary";
         added: "added";
         modified: "modified";
         renamed: "renamed";
-        unchanged: "unchanged";
         too_large: "too_large";
     }>;
     before: z.ZodNullable<z.ZodObject<{
@@ -2091,11 +2100,11 @@ export declare const spaceVersionFileDiffResponseSchema: z.ZodObject<{
         oldPath: z.ZodNullable<z.ZodString>;
         status: z.ZodEnum<{
             deleted: "deleted";
+            unchanged: "unchanged";
             binary: "binary";
             added: "added";
             modified: "modified";
             renamed: "renamed";
-            unchanged: "unchanged";
             too_large: "too_large";
         }>;
         before: z.ZodNullable<z.ZodObject<{

package/dist/contracts/spaces.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { AsyncOperationSchema, baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema, } from "./common.js";
 import { versionStatus, spaceStatus } from "./enums.js";
 import { conventionFilesSchema, uploadInstructionsSchema, manifestFileSchema } from "./internal.js";
-import { ChannelPointerSchema, VersionSchema, PublishSourceSchema, SpaceSchema, } from "./resources.js";
+import { ChannelPointerSchema, VersionSchema, PublishSourceSchema, SpaceSchema, spaceSettingsDigestSchema, } from "./resources.js";
 import { spaceConfigSchema, spacePlacementConfigSchema } from "./space-config.js";
 import { principalIdSchema } from "./transfers.js";
 import { zeroRuntimeKindSchema } from "./zero.js";
@@ -67,12 +67,20 @@ export const spaceCreateSchema = z
 })
     .optional()
     .default({});
-export const spacePatchSchema = z.object({
+export const spacePatchSchema = z
+    .object({
     title: z.string().min(1).max(255).optional(),
     config: spaceConfigSchema
         .nullable()
         .optional()
         .describe("Replaces the stored SpaceConfig overlay; null clears it."),
+    baseSettingsDigest: spaceSettingsDigestSchema
+        .optional()
+        .describe("Optimistic-concurrency base for versioned settings (title/config): the `settingsDigest` read from the Space resource when the form was loaded. When provided and the space's current settings digest no longer matches, the PATCH fails with 409 publish_base_changed and changes nothing."),
+    force: z
+        .boolean()
+        .optional()
+        .describe("With baseSettingsDigest: acknowledge a changed base and overwrite anyway. The forced overwrite is recorded in the space activity feed. Never the default."),
     dataLocation: z.string().min(1).optional(),
     placement: spacePlacementConfigSchema.optional(),
     noindex: z
@@ -86,6 +94,15 @@ export const spacePatchSchema = z.object({
         .nullable()
         .optional()
         .describe("Sets (string) or removes (null) space password protection."),
+})
+    .superRefine((value, ctx) => {
+    if (value.force === true && value.baseSettingsDigest === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "force requires baseSettingsDigest.",
+            path: ["force"],
+        });
+    }
 });
 export const spaceClaimSchema = z
     .object({
@@ -221,6 +238,9 @@ export const spaceVersionCreateSchema = z
         .max(64_000)
         .optional()
         .describe("Bounded build transcript for deploys that ran a local build before publishing."),
+    conventionFiles: conventionFilesSchema
+        .optional()
+        .describe("Routing convention contents used when deciding whether this publish is unchanged. The same values are supplied again when the version is finalized."),
     files: z
         .array(manifestFileSchema)
         .optional()

package/dist/contracts/superadmin-spaces.d.ts

@@ -298,6 +298,7 @@ export declare const SuperadminSpaceDetailSchema: z.ZodObject<{
                 noscript: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        settingsDigest: z.ZodString;
         noindex: z.ZodBoolean;
         policy: z.ZodNullable<z.ZodObject<{
             rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -706,6 +707,7 @@ export declare const SuperadminAnonymousSpaceAssignResponseSchema: z.ZodObject<{
                 noscript: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        settingsDigest: z.ZodString;
         noindex: z.ZodBoolean;
         policy: z.ZodNullable<z.ZodObject<{
             rules: z.ZodDefault<z.ZodArray<z.ZodObject<{

package/dist/contracts/superadmin-tenants.d.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 export declare const SuperadminProviderClientSchema: z.ZodObject<{
     id: z.ZodString;
     provider: z.ZodLiteral<"wpcloud">;
-    tenantId: z.ZodNullable<z.ZodString>;
+    tenantId: z.ZodString;
     name: z.ZodString;
     label: z.ZodString;
     apiBase: z.ZodNullable<z.ZodString>;
@@ -20,7 +20,7 @@ export declare const SuperadminProviderClientListSchema: z.ZodObject<{
     clients: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         provider: z.ZodLiteral<"wpcloud">;
-        tenantId: z.ZodNullable<z.ZodString>;
+        tenantId: z.ZodString;
         name: z.ZodString;
         label: z.ZodString;
         apiBase: z.ZodNullable<z.ZodString>;
@@ -42,7 +42,7 @@ export declare const superadminProviderClientCreateSchema: z.ZodObject<{
     apiBase: z.ZodOptional<z.ZodString>;
     defaultDatacenter: z.ZodOptional<z.ZodString>;
     defaultPhpVersion: z.ZodOptional<z.ZodString>;
-    tenantId: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodString;
 }, z.core.$strip>;
 export declare const superadminProviderClientPatchSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
@@ -54,7 +54,7 @@ export declare const superadminProviderClientPatchSchema: z.ZodObject<{
         active: "active";
         disabled: "disabled";
     }>>;
-    tenantId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    tenantId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const superadminProviderClientTestResponseSchema: z.ZodObject<{
     ok: z.ZodBoolean;
@@ -83,7 +83,7 @@ export declare const SuperadminTenantSchema: z.ZodObject<{
     providerClient: z.ZodNullable<z.ZodObject<{
         id: z.ZodString;
         provider: z.ZodLiteral<"wpcloud">;
-        tenantId: z.ZodNullable<z.ZodString>;
+        tenantId: z.ZodString;
         name: z.ZodString;
         label: z.ZodString;
         apiBase: z.ZodNullable<z.ZodString>;
@@ -125,7 +125,7 @@ export declare const SuperadminTenantListSchema: z.ZodObject<{
         providerClient: z.ZodNullable<z.ZodObject<{
             id: z.ZodString;
             provider: z.ZodLiteral<"wpcloud">;
-            tenantId: z.ZodNullable<z.ZodString>;
+            tenantId: z.ZodString;
             name: z.ZodString;
             label: z.ZodString;
             apiBase: z.ZodNullable<z.ZodString>;

package/dist/contracts/superadmin-tenants.js

@@ -4,16 +4,13 @@ import { providerClientStatus, tenantKind, tenantStatus } from "./enums.js";
 import { superadminPaginationSchema } from "./superadmin.js";
 // ProviderClient (`pvc_`) = one WP.Cloud API client identity sites are
 // provisioned under (internal-docs/platform.md "ProviderClient"). Operator-only
-// resource. `tenantId` is null for the Spacefast first-party client; a tenant
-// bringing its own WP.Cloud account owns exactly one row. The API token is
-// write-only; responses expose only a masked hint, never the secret.
+// resource. Each row is a tenant-owned BYO account; the first-party client is
+// configured separately as the platform context. The API token is write-only;
+// responses expose only a masked hint, never the secret.
 export const SuperadminProviderClientSchema = z.object({
     id: z.string().describe("ProviderClient id (`pvc_`)."),
     provider: z.literal("wpcloud").describe("Hosting provider this client identity belongs to."),
-    tenantId: z
-        .string()
-        .nullable()
-        .describe("Owning tenant; null for the Spacefast first-party client."),
+    tenantId: z.string().describe("Tenant that owns this WP.Cloud account."),
     name: z.string().describe("The WP.Cloud client/account name used as the {client} path param."),
     label: z.string().describe("Human-readable operator label."),
     apiBase: z.string().nullable().describe("API base URL override; null uses the default."),
@@ -51,8 +48,7 @@ export const superadminProviderClientCreateSchema = z.object({
     apiBase: z.string().url().optional(),
     defaultDatacenter: z.string().trim().min(1).optional(),
     defaultPhpVersion: z.string().trim().min(1).optional(),
-    // Connect the client to a tenant at creation; omit for the first-party client.
-    tenantId: z.string().trim().min(1).optional(),
+    tenantId: z.string().trim().min(1),
 });
 export const superadminProviderClientPatchSchema = z.object({
     label: z.string().trim().min(1).max(255).optional(),
@@ -62,8 +58,7 @@ export const superadminProviderClientPatchSchema = z.object({
     defaultDatacenter: z.string().trim().min(1).nullable().optional(),
     defaultPhpVersion: z.string().trim().min(1).nullable().optional(),
     status: providerClientStatus.optional(),
-    // Connect/disconnect the owning tenant (null disconnects → first-party pool).
-    tenantId: z.string().trim().min(1).nullable().optional(),
+    tenantId: z.string().trim().min(1).optional(),
 });
 // Live connectivity check against the client's WP.Cloud account.
 export const superadminProviderClientTestResponseSchema = z.object({

package/dist/contracts/teams.d.ts

@@ -197,17 +197,14 @@ export declare const teamSettingsResponseSchema: z.ZodObject<{
         label: z.ZodString;
     }, z.core.$strip>>;
     wpCloudCapabilities: z.ZodObject<{
-        status: z.ZodEnum<{
-            failed: "failed";
-            ready: "ready";
-            running: "running";
-            idle: "idle";
-        }>;
-        degraded: z.ZodBoolean;
-        lastSyncedAt: z.ZodNullable<z.ZodString>;
-        lastError: z.ZodNullable<z.ZodString>;
-        regionCount: z.ZodNumber;
-        phpVersionCount: z.ZodNumber;
+        datacenters: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
+        phpVersions: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const teamUsageResponseSchema: z.ZodObject<{

package/dist/contracts/teams.js

@@ -107,29 +107,24 @@ export const teamDataLocationSchema = z
 export const teamSettingsUpdateSchema = z.object({
     defaultDataLocation: teamDataLocationSchema,
 });
+const wpCloudCapabilityOptionSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+});
 // Served by `GET /v1/teams/{teamId}/settings` (and echoed by the PATCH):
 // the default data location plus the placement options it may take.
 export const teamSettingsResponseSchema = z.object({
     teamId: z.string().describe("Team the settings belong to."),
     defaultDataLocation: teamDataLocationSchema,
     regionOptions: z
-        .array(z.object({
-        id: z.string().describe("Placement region id."),
-        label: z.string().describe("Human-readable region label."),
-    }))
+        .array(wpCloudCapabilityOptionSchema)
         .describe("Placement regions currently available for new spaces."),
     wpCloudCapabilities: z
         .object({
-        status: z
-            .enum(["idle", "running", "ready", "failed"])
-            .describe("State of the provider capability sync."),
-        degraded: z.boolean().describe("Whether the last sync finished with an error."),
-        lastSyncedAt: z.string().nullable().describe("When capabilities last synced."),
-        lastError: z.string().nullable().describe("Last sync error, if any."),
-        regionCount: z.number().int().describe("Known placement regions."),
-        phpVersionCount: z.number().int().describe("Known runtime PHP versions."),
+        datacenters: z.array(wpCloudCapabilityOptionSchema),
+        phpVersions: z.array(wpCloudCapabilityOptionSchema),
     })
-        .describe("Provider capability sync status backing the region options."),
+        .describe("Live capabilities for the team's WP.Cloud provider account."),
 });
 // Served by `GET /v1/teams/{teamId}/usage`: counts and metered usage against
 // the named plan limits.
@@ -180,9 +175,9 @@ export const teamUpdateSchema = z
         .trim()
         .min(1)
         .max(255)
-        .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/, {
-        message: "Team slugs must contain lowercase letters, numbers, and hyphens.",
-    })
+        // Keep canonical guidance in OpenAPI without rejecting an exact legacy
+        // no-op before the shared policy can preserve its stored bytes.
+        .meta({ pattern: "^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$" })
         .optional(),
     logo: z.string().trim().max(2048).nullable().optional(),
     metadata: z.string().nullable().optional(),

package/dist/docs/agent-setup.d.ts

@@ -1,6 +1,57 @@
+import { type ConnectTargetId } from "../agents/connect-targets.js";
 export declare const agentSetupUrl: string;
 export declare const agentSetupTextUrl: string;
 export declare const agentSetupHostLabel: string;
 export declare const agentSetupPrompt: string;
+/**
+ * Typed, safe decline states for the app-private redemption exchange.
+ * `invalid_handoff` is the single answer for both an unknown document ID and a wrong secret, so a
+ * decline never becomes an existence oracle; state-specific reasons are returned only after the
+ * supplied secret authenticates the handoff. `already_redeemed` makes one-use explicit: after the
+ * first exchange succeeds, the second fails with this reason. Declines are terminal and never
+ * reveal whether a secret was close to correct.
+ */
+export declare const AGENT_HANDOFF_DECLINE_REASONS: readonly ["invalid_handoff", "expired", "already_redeemed", "revoked", "client_mismatch", "origin_mismatch"];
+export type AgentHandoffDeclineReason = (typeof AGENT_HANDOFF_DECLINE_REASONS)[number];
+export type AgentHandoffAction = Readonly<{
+    kind: "copy";
+    label: string;
+    sensitive: boolean;
+    value: string;
+}> | Readonly<{
+    kind: "open";
+    label: string;
+    href: string;
+}>;
+export type AgentHandoff = Readonly<{
+    actions: readonly AgentHandoffAction[];
+    documentUrl: string;
+    instructions: string;
+    prompt: string;
+}>;
+/**
+ * The single shared grammar for handoff links:
+ * `https://<app-origin>/agent/<documentId>#<secret>`. The document ID must match
+ * `[A-Za-z0-9_-]{1,512}` and the secret `[A-Za-z0-9_-]{16,512}` (the minimum keeps secrets
+ * high-entropy and makes the public-projection leak check meaningful); the two must differ;
+ * queries and embedded credentials are forbidden; HTTPS is required except on loopback hosts.
+ * Normalization is part of the contract: the input is WHATWG-URL-normalized first (backslashes,
+ * dot segments, stray tab/CR/LF, empty userinfo, case, default ports), the grammar is enforced on
+ * the normalized URL, and only the reconstructed canonical URL ever leaves this function.
+ * Dashboard minting, CLI ingestion, and control-plane validation must all use this parser so the
+ * grammar can never fork.
+ */
+export declare function parseAgentHandoffUrl(value: string, expectedOrigin: string): Readonly<{
+    documentId: string;
+    documentUrl: string;
+    secret: string;
+}>;
+/** Builds every copy-ready handoff artifact from one validated URL and target catalog row. */
+export declare function buildAgentHandoff(input: {
+    expectedOrigin: string;
+    mcpEndpoint: string;
+    targetId: ConnectTargetId;
+    url: string;
+}): AgentHandoff;
 export declare function renderAgentSetupTemplate(value: string): string;
 export declare function aiInstructionsText(): string;

package/dist/docs/agent-setup.js

@@ -1,11 +1,176 @@
-import { BRAND } from "@spacefast/common/brand";
-import { CHECK_BEFORE_PUBLISH_PROSE, CONTINUE_AFTER_CLAIM_PROSE, ENV_NOTES_PROSE, FAILURE_CONDUCT_PROSE, HOW_TO_RESEARCH_PROSE, LANE_PICKER_PROSE, POSITIONING_PROSE, PUBLISH_SEQUENCE_PROSE, RECEIPT_SHAPE_PROSE, SAVE_STATE_PROSE, SECRET_RULES_PROSE, SIGNED_UPLOAD_PROSE, UPDATE_SPACE_PROSE, } from "@spacefast/common/docs/agent-prose";
-import { spacefastInstallCurlCommand, spacefastInstallPowerShellCommand, spacefastSkillFetchCommand, spacefastSkillInstallCommand, spacefastSkillUrl, } from "@spacefast/common/docs/skill-distribution";
+import { getConnectTarget, } from "../agents/connect-targets.js";
+import { BRAND } from "../brand.js";
+import { CHECK_BEFORE_PUBLISH_PROSE, CONTINUE_AFTER_CLAIM_PROSE, ENV_NOTES_PROSE, FAILURE_CONDUCT_PROSE, HOW_TO_RESEARCH_PROSE, LANE_PICKER_PROSE, POSITIONING_PROSE, PUBLISH_SEQUENCE_PROSE, RECEIPT_SHAPE_PROSE, SAVE_STATE_PROSE, SECRET_RULES_PROSE, SIGNED_UPLOAD_PROSE, UPDATE_SPACE_PROSE, } from "./agent-prose.js";
+import { spacefastInstallCurlCommand, spacefastInstallPowerShellCommand, spacefastSkillFetchCommand, spacefastSkillInstallCommand, spacefastSkillUrl, } from "./skill-distribution.js";
 export const agentSetupUrl = `${BRAND.agentSetupOrigin}/ai`;
 export const agentSetupTextUrl = `${BRAND.agentSetupOrigin}/ai.txt`;
 const agentSetupParsedUrl = new URL(agentSetupUrl);
 export const agentSetupHostLabel = agentSetupParsedUrl.host + agentSetupParsedUrl.pathname;
 export const agentSetupPrompt = `Fetch ${agentSetupUrl} and follow it to publish this project — or update it if it's already on ${BRAND.productName}. Ask me what I want to publish if it isn't obvious.`;
+/*
+ * Agent handoff contract: links use https://<app-origin>/agent/<documentId>#<secret>, with
+ * opaque document IDs and secrets. The fragment is the secret, so ordinary document fetches
+ * never send or reveal it. Fetching never consumes a handoff; exactly one successful redemption
+ * does. Redemption is app-private, reuses the existing device/OAuth approval service, and returns
+ * the already-approved finite Space-scoped credential: there is no public AgentGrant resource,
+ * durable key table, or team-wide publisher key. The CLI accepts links only through stdin or a
+ * browser callback and redacts them from JSON output, telemetry, shell history, doctor, and
+ * receipts. The dashboard can revoke an unused handoff.
+ */
+const opaqueHandoffDocumentId = /^[A-Za-z0-9_-]{1,512}$/;
+const opaqueHandoffSecret = /^[A-Za-z0-9_-]{16,512}$/;
+const shellSafeMcpEndpoint = /^[A-Za-z0-9%+,\-./:=_[\]~]+$/;
+/**
+ * Typed, safe decline states for the app-private redemption exchange.
+ * `invalid_handoff` is the single answer for both an unknown document ID and a wrong secret, so a
+ * decline never becomes an existence oracle; state-specific reasons are returned only after the
+ * supplied secret authenticates the handoff. `already_redeemed` makes one-use explicit: after the
+ * first exchange succeeds, the second fails with this reason. Declines are terminal and never
+ * reveal whether a secret was close to correct.
+ */
+export const AGENT_HANDOFF_DECLINE_REASONS = [
+    "invalid_handoff",
+    "expired",
+    "already_redeemed",
+    "revoked",
+    "client_mismatch",
+    "origin_mismatch",
+];
+function isSafeHttpUrl(url) {
+    return ((url.protocol === "https:" ||
+        (url.protocol === "http:" &&
+            (url.hostname === "localhost" ||
+                url.hostname === "127.0.0.1" ||
+                url.hostname === "[::1]"))) &&
+        !url.username &&
+        !url.password);
+}
+/**
+ * The single shared grammar for handoff links:
+ * `https://<app-origin>/agent/<documentId>#<secret>`. The document ID must match
+ * `[A-Za-z0-9_-]{1,512}` and the secret `[A-Za-z0-9_-]{16,512}` (the minimum keeps secrets
+ * high-entropy and makes the public-projection leak check meaningful); the two must differ;
+ * queries and embedded credentials are forbidden; HTTPS is required except on loopback hosts.
+ * Normalization is part of the contract: the input is WHATWG-URL-normalized first (backslashes,
+ * dot segments, stray tab/CR/LF, empty userinfo, case, default ports), the grammar is enforced on
+ * the normalized URL, and only the reconstructed canonical URL ever leaves this function.
+ * Dashboard minting, CLI ingestion, and control-plane validation must all use this parser so the
+ * grammar can never fork.
+ */
+export function parseAgentHandoffUrl(value, expectedOrigin) {
+    let canonicalExpectedOrigin;
+    try {
+        canonicalExpectedOrigin = new URL(expectedOrigin).origin;
+    }
+    catch {
+        throw new TypeError("Agent handoff expectedOrigin must be a valid URL origin.");
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TypeError("Agent handoff URL must be a valid HTTP(S) URL.");
+    }
+    const documentId = /^\/agent\/([^/]+)$/.exec(url.pathname)?.[1];
+    const secret = url.hash.slice(1);
+    if (!isSafeHttpUrl(url) ||
+        url.origin !== canonicalExpectedOrigin ||
+        value.includes("?") ||
+        !documentId ||
+        !opaqueHandoffDocumentId.test(documentId) ||
+        !opaqueHandoffSecret.test(secret) ||
+        documentId === secret) {
+        throw new TypeError("Agent handoff URL must be an HTTPS /agent/<id> URL with one opaque fragment secret (16-512 chars, distinct from the id) and no credentials or query (HTTP is allowed on loopback hosts).");
+    }
+    return { documentId, documentUrl: `${url.origin}${url.pathname}`, secret };
+}
+function validateMcpEndpoint(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TypeError("MCP endpoint must be a valid HTTP(S) URL.");
+    }
+    if (!shellSafeMcpEndpoint.test(value) || !isSafeHttpUrl(url)) {
+        throw new TypeError("MCP endpoint must be a shell-safe HTTPS URL with no credentials, query, fragment, or control characters (HTTP is allowed on loopback hosts).");
+    }
+    return url.href.replace(/\/$/, "");
+}
+function renderAgentHandoffInstructions(documentUrl, target) {
+    const setupSections = [target.primary, target.config].flatMap((setup) => setup ? [[setup.label, `\`\`\`${setup.language}`, setup.value, "```"].join("\n")] : []);
+    const connectSections = [
+        target.blurb,
+        ...setupSections,
+        target.deeplink ? `${target.deeplink.label}: ${target.deeplink.href}` : null,
+        target.download ? `${target.download.label}: ${target.download.href}` : null,
+    ].filter((section) => section !== null);
+    const approvalGuidance = target.id === "claude-code" || target.id === "codex"
+        ? `Run \`sf setup agent\` to initiate the handoff exchange; if \`sf\` is missing, install it first (macOS/Linux: \`${spacefastInstallCurlCommand}\`; Windows PowerShell: \`${spacefastInstallPowerShellCommand}\`). When it asks for the handoff link on stdin, paste the original link into that prompt; never pass the link as an argv value. Ask the user to approve in the browser, then wait for the CLI's approval result before publishing.`
+        : "When the client opens browser approval, ask the user to approve there before publishing.";
+    const sections = [
+        `# Set up ${BRAND.productName} with ${target.name}`,
+        `This is the public setup document for ${documentUrl}.`,
+        "Talk to the user before installing tools or publishing. Confirm the file or folder they want to make public.",
+        ["## Connect", ...connectSections].join("\n\n"),
+        [
+            "## Continue the approved handoff",
+            "Keep the original handoff link private. Fetching this document did not use the link or send its fragment secret; the secret is spent only by one successful exchange. An expired, used, or revoked link fails safely, so ask the user for a fresh one from the dashboard.",
+            approvalGuidance,
+            "Keep its fragment out of commands, request URLs, logs, and replies.",
+        ].join("\n\n"),
+        [
+            "## Publish",
+            "After approval, confirm the selected Space and permissions, then publish only the files the user approved. Share the live URL and immutable version URL from the receipt.",
+        ].join("\n\n"),
+        `General agent instructions: ${agentSetupTextUrl}`,
+    ];
+    return `${sections.join("\n\n")}\n`;
+}
+/** Builds every copy-ready handoff artifact from one validated URL and target catalog row. */
+export function buildAgentHandoff(input) {
+    const { documentUrl, secret } = parseAgentHandoffUrl(input.url, input.expectedOrigin);
+    const mcpEndpoint = validateMcpEndpoint(input.mcpEndpoint);
+    const target = getConnectTarget(input.targetId, {
+        mcpEndpoint,
+    });
+    const prompt = `Fetch ${documentUrl}#${secret} and follow the ${target.name} setup instructions to publish with ${BRAND.productName}. Ask me what I want to publish if it isn't obvious.`;
+    const instructions = renderAgentHandoffInstructions(documentUrl, target);
+    const actions = [
+        { kind: "copy", label: "Copy for my agent", sensitive: true, value: prompt },
+        { kind: "copy", label: "Copy Markdown", sensitive: false, value: instructions },
+    ];
+    if (target.deeplink) {
+        actions.push({
+            kind: "open",
+            label: target.deeplink.label,
+            href: target.deeplink.href,
+        });
+    }
+    if (target.download) {
+        actions.push({
+            kind: "open",
+            label: target.download.label,
+            href: target.download.href,
+        });
+    }
+    // The scanner-safe invariant is total, not statistical: no public projection may contain the
+    // secret, no matter what the caller fed in (a pathological mint, a poisoned MCP endpoint).
+    const publicProjections = [
+        documentUrl,
+        instructions,
+        ...actions.flatMap((action) => {
+            if (action.kind === "open")
+                return [action.href];
+            return action.sensitive ? [] : [action.value];
+        }),
+    ];
+    if (publicProjections.some((projection) => projection.includes(secret))) {
+        throw new TypeError("Agent handoff inputs would leak the fragment secret into a public projection.");
+    }
+    return { actions, documentUrl, instructions, prompt };
+}
 export function renderAgentSetupTemplate(value) {
     return value
         .replaceAll("{{AGENT_SETUP_URL}}", agentSetupUrl)