@spacefast/common 0.2.1 → 0.4.1

package/dist/docs/skills.js

@@ -1,11 +1,27 @@
 import { DOCS_BASE_URL } from "../config/domains.js";
 const BOTH_RUNTIMES = ["local", "hosted"];
 const PUBLISH_CONTINUATION_INSTRUCTIONS = [
-    "If `publish.result.status` is `publishing`, call `operation_status` with `publish.result.job.poll.operationId`.",
+    "For authenticated `publish`, set a unique `requestId` before the first call. Reuse it only with the same input after uncertainty.",
+    "If `publish.result.status` is `publishing`, call `operation_status`. Use `publish.result.job.poll.url` when present. Otherwise, use `publish.result.job.poll.operationId`.",
     "Call `operation_status` again only while `operation_status.result.done` is false.",
+    "Wait two seconds between publish status reads.",
     "Continue only when `operation_status.result.status` is `succeeded`.",
     "Report `failed` or `canceled` and stop.",
 ];
+const UNCLAIMED_PUBLISH_VERIFICATION = "If `publish.result.receipt.claim` is present, use the completed publish receipt as verification. Do not call `show_space`. The user must claim the Space before you open a detailed view.";
+const EXECUTE_CONTINUATION_INSTRUCTIONS = [
+    "Before editing an existing Space, read `get_work_mode`. If mode is null, open `show_work_mode` and wait for the user's choice.",
+    "In vibe mode, handle routine source steps internally. Disable configured automatic deployment before committing. Build with `{preview:false,channel:null}`.",
+    "Show the exact ready version as a visual preview. Request publishing approval separately. Do not show code or diff Apps unless asked.",
+    "In code mode, show the existing files, diffs, commit history, and build logs for review. Reuse the saved mode on later requests.",
+    "Describe each selected path with `tools.describe.tool({ path: item.path })`. Read `inputTypeScript` and `outputTypeScript` before calling it.",
+    "Check `result.ok`. The HTTP body is `result.data`; a Spacefast JSON success envelope contains its payload at `result.data.data`.",
+    "If `execute` pauses, follow its `resumePrompt`.",
+    "For an MCP App approval, call `resume_execution` with only the same `executionId` to open the card.",
+    "Wait for the card's user message before calling it again. Browser approval also resumes with only `executionId` after the user acts.",
+    "For an On-Device form approval, send the requested action and content only after the user approves.",
+    "Do not start another program. `resume_execution` continues the saved program.",
+];
 /** Canonical agent workflows shared by MCP tools, prompts, resources, and recipe docs. */
 export const SPACEFAST_SKILLS = [
     {
@@ -15,7 +31,7 @@ export const SPACEFAST_SKILLS = [
         whenToUse: "Use when the user wants a new website built, improved, or launched.",
         keywords: ["create", "website", "design", "build", "responsive", "launch", "publish"],
         runtimes: BOTH_RUNTIMES,
-        tools: ["publish", "operation_status", "show_space_deployments"],
+        tools: ["publish", "operation_status", "show_space"],
         docs: ["quickstart", "publishing"],
         instructions: [
             "Use the user's brief. Infer optional design choices from the content and workspace.",
@@ -28,12 +44,13 @@ export const SPACEFAST_SKILLS = [
             ...PUBLISH_CONTINUATION_INSTRUCTIONS,
         ],
         verification: [
-            "Call `show_space_deployments` with `space: publish.result.receipt.space.id`. Confirm that the intended version is ready and current.",
+            UNCLAIMED_PUBLISH_VERIFICATION,
+            'If `publish.result.receipt.claim` is absent, call `show_space` with `request.view: "deployments"` and `request.input.space: publish.result.receipt.space.id`. Confirm that the intended version is ready and current.',
             "If the deployment failed or stalled, report its stable error code and actionable diagnostics.",
-            "Open the live URL. Verify the main page, navigation, assets, responsive layout, and primary call to action.",
+            "For a claimed Space, open its access URL. Verify the main page, navigation, assets, responsive layout, and primary call to action.",
         ],
         runtimeNotes: {
-            local: "On-Device can work directly inside the configured local workspace root and publish a local build path.",
+            local: "On Linux, On-Device can publish a build path relative to the configured workspace root. On other systems, publish new artifacts inline or use a permitted CLI or HTTP upload.",
             hosted: "Hosted has no filesystem. Generate small files in the client and publish them inline, or use catalog manifest and import operations for larger artifacts.",
         },
         prompt: true,
@@ -50,7 +67,7 @@ export const SPACEFAST_SKILLS = [
         whenToUse: "Use when the artifact already exists and the user wants it published or updated.",
         keywords: ["publish", "deploy", "live", "verify", "version", "claim"],
         runtimes: BOTH_RUNTIMES,
-        tools: ["publish", "operation_status", "show_space_deployments"],
+        tools: ["publish", "operation_status", "show_space"],
         docs: ["publishing", "workflow/publish-receipt", "workflow/secret-handling"],
         instructions: [
             "Identify the actual publish root or build output. Run the real build first when the source tree is not the artifact.",
@@ -60,9 +77,10 @@ export const SPACEFAST_SKILLS = [
             "Never expose a raw claim credential. Never ask the user to paste one.",
         ],
         verification: [
-            "Call `show_space_deployments` with `space: publish.result.receipt.space.id`. Confirm that the intended version is ready and current.",
+            UNCLAIMED_PUBLISH_VERIFICATION,
+            'If `publish.result.receipt.claim` is absent, call `show_space` with `request.view: "deployments"` and `request.input.space: publish.result.receipt.space.id`. Confirm that the intended version is ready and current.',
             "Report the stable error code and actionable diagnostics when the deployment failed or stalled.",
-            "Open the live URL. Verify representative content and assets before reporting success.",
+            "For a claimed Space, open its access URL. Verify representative content and assets before reporting success.",
         ],
         runtimeNotes: {
             local: "Publish a bounded local path; locally custodied claim credentials are reused automatically.",
@@ -114,20 +132,24 @@ export const SPACEFAST_SKILLS = [
         whenToUse: "Use when reviewers need a realistic preview before a change goes live.",
         keywords: ["preview", "channel", "branch", "pull request", "review", "private"],
         runtimes: BOTH_RUNTIMES,
-        tools: ["publish", "operation_status", "show_space_deployments", "execute", "resume_execution"],
+        tools: ["publish", "operation_status", "show_space", "execute", "resume_execution"],
         docs: ["builds", "access-control"],
         instructions: [
-            "Call `publish` once for an explicit non-production space or channel. Do not change the production target.",
+            "Use `publish` for a separate preview Space. Pass its `spaceId`, or set `createNew: true` when the user requests a new Space.",
+            "For a source preview in an existing Space, describe `createSpaceBuild` through `execute`. Use a repository input pinned to the saved commit.",
+            "Set `body.target` to `{ preview: true, channel: null }`. Set the described `Idempotency-Key` header and keep `wait` false.",
+            "Poll `getBuild` until it succeeds or fails. A build response does not prove that a version is live.",
+            "Direct `publish` has no channel input. Keep the production target unchanged.",
             ...PUBLISH_CONTINUATION_INSTRUCTIONS,
             "Keep the preview private unless the user requests sharing.",
             "For reviewer access, use one bounded `execute` program. Read current access, create the narrowest Link, then read it again.",
-            "If `execute` pauses, follow its `resumePrompt`. Then call `resume_execution` with the returned `executionId`.",
-            "Do not start another `execute` program.",
+            ...EXECUTE_CONTINUATION_INSTRUCTIONS,
             "Label the preview with its branch, change, or pull request. Report what is out of scope.",
         ],
         verification: [
-            "Call `show_space_deployments` for each affected Space. Confirm that the preview changed. Confirm that production did not change.",
-            "Test the reviewer Link in a signed-out context. Report its scope and expiry.",
+            UNCLAIMED_PUBLISH_VERIFICATION,
+            'If `publish.result.receipt.claim` is absent, call `show_space` with `request.view: "deployments"` and `request.input.space` set to each affected Space. Confirm that the preview changed. Confirm that production did not change.',
+            "If `publish.result.receipt.claim` is absent, test the reviewer Link in a signed-out context. Report its scope and expiry.",
         ],
         recipe: {
             slug: "recipes/preview-channels",
@@ -146,18 +168,17 @@ export const SPACEFAST_SKILLS = [
         docs: ["anonymous-publish", "workflow/continue-after-claim", "workflow/secret-handling"],
         instructions: [
             "Point the user to the claim action in the publish card and state its expiry. Never copy the claim credential into model text.",
-            "When account credentials are available, use one bounded `execute` program. Search and describe the claim operation before calling it.",
-            "Pass only the required team ID and expected space ID.",
-            "After the claim resumes, read the space in the same program. Return its owner and claim state.",
-            "If `execute` pauses, follow its `resumePrompt`. Then call `resume_execution` with the returned `executionId`.",
-            "Do not start another `execute` program.",
-            "Otherwise, ask the user to use the claim action in the publish card.",
-            "After a browser claim, call `publish` again from On-Device. It exchanges the locally held credential without exposing it.",
+            "Let the user complete the claim through the publish card. The card keeps the claim credential outside model text.",
+            "After the claim, use one bounded `execute` program with the connected account to read the Space by its known ID.",
+            "Return its owner and claim state. Do not extract the saved claim key or call its exchange through `execute`.",
+            ...EXECUTE_CONTINUATION_INSTRUCTIONS,
+            "If account access is unavailable, reconnect Spacefast in the client.",
+            "The next requested On-Device publish exchanges the locally held credential automatically without exposing it.",
             ...PUBLISH_CONTINUATION_INSTRUCTIONS,
         ],
         verification: [
             "Confirm that the space has no claim expiry. Confirm that it belongs to the intended account or team.",
-            "Confirm that the republish uses durable access without a raw credential.",
+            "When the user next requests a publish, confirm that it succeeds through the saved credential without exposing it.",
         ],
         prompt: true,
     },
@@ -168,17 +189,16 @@ export const SPACEFAST_SKILLS = [
         whenToUse: "Use when the current live version is broken and a prior healthy version is known or discoverable.",
         keywords: ["rollback", "revert", "version", "incident", "restore"],
         runtimes: BOTH_RUNTIMES,
-        tools: ["show_space_deployments", "execute", "resume_execution"],
+        tools: ["show_space", "execute", "resume_execution"],
         docs: ["versions-and-rollback"],
         instructions: [
-            "Call `show_space_deployments`. Select a known-good ready version that is older than the current version.",
+            'Call `show_space` with `request.view: "deployments"` and `request.input.space` set to the affected Space. Select a known-good ready version that is older than the current version.',
             "Use one bounded `execute` program. Search and describe the version promotion operation before calling it.",
             "Read the live pointer, promote the selected version, then read the pointer again in the same program.",
-            "If `execute` pauses, follow its `resumePrompt`. Then call `resume_execution` with the returned `executionId`.",
-            "Do not start another `execute` program.",
+            ...EXECUTE_CONTINUATION_INSTRUCTIONS,
         ],
         verification: [
-            "Call `show_space_deployments`. Confirm that the selected version is current and ready.",
+            'Call `show_space` with `request.view: "deployments"` and `request.input.space` set to the affected Space. Confirm that the selected version is current and ready.',
             "Open the live URL. Verify that the failing path or behavior works again.",
         ],
         prompt: true,
@@ -190,19 +210,18 @@ export const SPACEFAST_SKILLS = [
         whenToUse: "Use when the user owns a domain they want a Spacefast space to serve.",
         keywords: ["domain", "dns", "tls", "https", "cname", "custom"],
         runtimes: BOTH_RUNTIMES,
-        tools: ["show_space_domains", "execute", "resume_execution"],
+        tools: ["show_space", "execute", "resume_execution"],
         docs: ["custom-domains", "recipes/migrate-dns"],
         instructions: [
-            "Call `show_space_domains`. Read the current domain, DNS, and certificate state.",
+            'Call `show_space` with `request.view: "domains"` and `request.input.space` set to the affected Space. Read the current domain, DNS, and certificate state.',
             "If setup is required, use one bounded `execute` program. Search and describe the add or assign operation before calling it.",
             "Read the domain again in the same program after the mutation resumes.",
-            "If `execute` pauses, follow its `resumePrompt`. Then call `resume_execution` with the returned `executionId`.",
-            "Do not start another `execute` program.",
+            ...EXECUTE_CONTINUATION_INSTRUCTIONS,
             "Return the exact DNS records from Spacefast. Do not claim that Spacefast changed third-party DNS.",
             "Keep the existing production hostname until the custom domain is ready.",
         ],
         verification: [
-            "After the external DNS change, call `show_space_domains`. Report the current verification state.",
+            'After the external DNS change, call `show_space` with `request.view: "domains"` and `request.input.space` set to the affected Space. Report the current verification state.',
             "Open the HTTPS URL only after DNS and certificate states are ready. Verify representative content.",
         ],
         prompt: true,
@@ -219,7 +238,7 @@ export const SPACEFAST_SKILLS = [
         whenToUse: "Use for moved pages, canonical host paths, and intentional permanent or temporary redirects.",
         keywords: ["redirect", "rewrite", "routing", "301", "302", "path"],
         runtimes: BOTH_RUNTIMES,
-        tools: ["publish", "operation_status", "show_space_deployments"],
+        tools: ["publish", "operation_status", "show_space"],
         docs: ["redirects"],
         instructions: [
             "Inspect existing routing rules, then add the smallest non-conflicting rules to `_redirects` at the publish root.",
@@ -229,9 +248,10 @@ export const SPACEFAST_SKILLS = [
             ...PUBLISH_CONTINUATION_INSTRUCTIONS,
         ],
         verification: [
-            "Call `show_space_deployments` with `space: publish.result.receipt.space.id`. Confirm that the new version is current and ready.",
-            "Request representative old and new paths and confirm the exact status and Location header.",
-            "Verify the final target serves successfully and unrelated assets are not redirected.",
+            UNCLAIMED_PUBLISH_VERIFICATION,
+            'If `publish.result.receipt.claim` is absent, call `show_space` with `request.view: "deployments"` and `request.input.space: publish.result.receipt.space.id`. Confirm that the new version is current and ready.',
+            "If `publish.result.receipt.claim` is absent, request representative old and new paths and confirm the exact status and Location header.",
+            "If `publish.result.receipt.claim` is absent, verify the final target serves successfully and unrelated assets are not redirected.",
         ],
         recipe: {
             slug: "recipes/redirects",
@@ -246,20 +266,19 @@ export const SPACEFAST_SKILLS = [
         whenToUse: "Use when an existing production domain must move to Spacefast.",
         keywords: ["dns", "migrate", "cutover", "domain", "downtime", "certificate"],
         runtimes: BOTH_RUNTIMES,
-        tools: ["show_space_domains", "execute", "resume_execution"],
+        tools: ["show_space", "execute", "resume_execution"],
         docs: ["custom-domains"],
         instructions: [
             "Inventory the current authoritative DNS records. Lower the TTL before cutover when the provider and timing permit it.",
-            "Call `show_space_domains`. Read the current DNS and certificate state.",
+            'Call `show_space` with `request.view: "domains"` and `request.input.space` set to the affected Space. Read the current DNS and certificate state.',
             "If setup is required, use one bounded `execute` program. Search and describe the add or assign operation before calling it.",
             "Read the domain again in the same program after the mutation resumes.",
-            "If `execute` pauses, follow its `resumePrompt`. Then call `resume_execution` with the returned `executionId`.",
-            "Do not start another `execute` program.",
+            ...EXECUTE_CONTINUATION_INSTRUCTIONS,
             "Create the returned DNS records at the provider. Keep the previous origin available during propagation.",
             "Cut over only after the expected content and TLS state are ready.",
         ],
         verification: [
-            "Call `show_space_domains`. Confirm that DNS and certificate states are ready.",
+            'Call `show_space` with `request.view: "domains"` and `request.input.space` set to the affected Space. Confirm that DNS and certificate states are ready.',
             "Check more than one resolver. Confirm that the certificate matches the final hostname.",
             "Open the public HTTPS URL. Verify representative content before removing rollback records.",
         ],
@@ -276,18 +295,19 @@ export const SPACEFAST_SKILLS = [
         whenToUse: "Use when a build, finalize, activation, or live serving step fails or stalls.",
         keywords: ["debug", "failed", "build", "logs", "diagnose", "stalled"],
         runtimes: BOTH_RUNTIMES,
-        tools: ["show_space_deployments", "execute", "publish", "operation_status"],
+        tools: ["show_space", "execute", "resume_execution", "publish", "operation_status"],
         docs: ["troubleshooting"],
         instructions: [
-            "Call `show_space_deployments`. Read the failed version, build state, stable error code, and diagnostics.",
+            'Call `show_space` with `request.view: "deployments"` and `request.input.space` set to the affected Space. Read the failed version, build state, stable error code, and diagnostics.',
             "If more detail is required, use one bounded `execute` program. Read only the required build logs or version data.",
             "Apply the smallest fix supported by the evidence. Run the real build.",
             "Call `publish` once with the fixed output.",
             ...PUBLISH_CONTINUATION_INSTRUCTIONS,
         ],
         verification: [
-            "Call `show_space_deployments` with `space: publish.result.receipt.space.id`. Confirm that the new version is current and ready.",
-            "Open the affected live path. Verify that the concrete failure does not occur.",
+            UNCLAIMED_PUBLISH_VERIFICATION,
+            'If `publish.result.receipt.claim` is absent, call `show_space` with `request.view: "deployments"` and `request.input.space: publish.result.receipt.space.id`. Confirm that the new version is current and ready.',
+            "If `publish.result.receipt.claim` is absent, open the affected live path. Verify that the concrete failure does not occur.",
         ],
         prompt: true,
     },
@@ -304,8 +324,7 @@ export const SPACEFAST_SKILLS = [
             "Use one bounded `execute` program. Search and describe the access operations before calling them.",
             "Read current access. Apply the narrowest change for one explicit access intent. Read the resulting access state.",
             "Run the matching access check in the same program after the mutation resumes.",
-            "If `execute` pauses, follow its `resumePrompt`. Then call `resume_execution` with the returned `executionId`.",
-            "Do not start another `execute` program.",
+            ...EXECUTE_CONTINUATION_INSTRUCTIONS,
             "Show new Link or machine secrets only to the requesting user. Never store them in logs or committed files.",
         ],
         verification: [

package/dist/docs/start-prompts.d.ts

@@ -22,6 +22,12 @@ export type StartShippingIntent = keyof typeof START_SHIPPING_INTENTS;
  * private handoff link.
  */
 export declare function teamContextLine(teamName: string): string;
+/**
+ * The existing space a copied prompt targets. The hostname is the identifier
+ * an agent can act on directly — the CLI and MCP tools both resolve a space
+ * from the domain it serves.
+ */
+export declare function spaceContextLine(host: string): string;
 /**
  * How a /start handoff prompt ends. The private-prompt builder's default
  * closing points back at "the page task" and "the references above", which is
@@ -37,6 +43,14 @@ export declare const START_HANDOFF_CLOSING = "Then ask me what to publish, and w
  */
 export declare function terminalLoginCommand(handoffUrl: string): string;
 export declare const TERMINAL_LOGIN_COMMAND_DISPLAY: string;
+/**
+ * The same paste-to-login, chained into the command the visitor actually came
+ * for. One paste signs the CLI in with the one-use link and then runs the
+ * follow-on — a surface offering "set up my git remote" should not make
+ * signing in a separate errand.
+ */
+export declare function terminalLoginThenCommand(handoffUrl: string, command: string): string;
+export declare function terminalLoginThenCommandDisplay(command: string): string;
 /**
  * Joins a base prompt with a shipping intent. An empty base means the copy
  * carries a handoff link that serves the setup itself, so the intent stands

package/dist/docs/start-prompts.js

@@ -32,6 +32,14 @@ export const START_SHIPPING_INTENTS = {
 export function teamContextLine(teamName) {
     return `Use my Spacefast team: ${teamName}.`;
 }
+/**
+ * The existing space a copied prompt targets. The hostname is the identifier
+ * an agent can act on directly — the CLI and MCP tools both resolve a space
+ * from the domain it serves.
+ */
+export function spaceContextLine(host) {
+    return `Publish to my existing space: ${host}.`;
+}
 /**
  * How a /start handoff prompt ends. The private-prompt builder's default
  * closing points back at "the page task" and "the references above", which is
@@ -49,6 +57,18 @@ export function terminalLoginCommand(handoffUrl) {
     return `printf '%s\\n' '${handoffUrl}' | sf login --handoff`;
 }
 export const TERMINAL_LOGIN_COMMAND_DISPLAY = terminalLoginCommand("<one-use link>");
+/**
+ * The same paste-to-login, chained into the command the visitor actually came
+ * for. One paste signs the CLI in with the one-use link and then runs the
+ * follow-on — a surface offering "set up my git remote" should not make
+ * signing in a separate errand.
+ */
+export function terminalLoginThenCommand(handoffUrl, command) {
+    return `${terminalLoginCommand(handoffUrl)} && ${command}`;
+}
+export function terminalLoginThenCommandDisplay(command) {
+    return terminalLoginThenCommand("<one-use link>", command);
+}
 /**
  * Joins a base prompt with a shipping intent. An empty base means the copy
  * carries a handoff link that serves the setup itself, so the intent stands

package/dist/utils/account-labels.d.ts

@@ -0,0 +1,7 @@
+type AccountIdentity = {
+    name?: string | null;
+    email: string;
+};
+export declare function getAccountDisplayName(account: AccountIdentity): string;
+export declare function getAccountSecondaryLabel(account: AccountIdentity): string;
+export {};

package/dist/utils/account-labels.js

@@ -0,0 +1,15 @@
+// Accounts carry a name and an email, no handle. The display name is the name
+// with a presentable email-derived fallback; the secondary line is the email,
+// shown only when it adds information the display name does not already carry.
+export function getAccountDisplayName(account) {
+    const name = account.name?.trim();
+    if (name)
+        return name;
+    const email = account.email.trim();
+    const at = email.indexOf("@");
+    return at > 0 ? email.slice(0, at) : email;
+}
+export function getAccountSecondaryLabel(account) {
+    const email = account.email.trim();
+    return email === getAccountDisplayName(account) ? "" : email;
+}

package/dist/utils/auth.d.ts

@@ -1,5 +1,6 @@
 export declare const SPACEFAST_TENANT_HEADER = "x-spacefast-tenant-id";
 export declare const SPACEFAST_CLIENT_HEADER = "x-spacefast-client";
 export declare const SPACEFAST_CLI_DEVICE_CLIENT_ID = "spacefast-cli";
+export declare const SPACEFAST_MCP_DEVICE_CLIENT_ID = "spacefast-mcp";
 export declare function normalizeDeviceUserCode(value: string): string;
 export declare function formatDeviceUserCode(value: string): string;

package/dist/utils/auth.js

@@ -1,6 +1,7 @@
 export const SPACEFAST_TENANT_HEADER = "x-spacefast-tenant-id";
 export const SPACEFAST_CLIENT_HEADER = "x-spacefast-client";
 export const SPACEFAST_CLI_DEVICE_CLIENT_ID = "spacefast-cli";
+export const SPACEFAST_MCP_DEVICE_CLIENT_ID = "spacefast-mcp";
 export function normalizeDeviceUserCode(value) {
     return value.replace(/[^a-z0-9]/gi, "").toUpperCase();
 }

package/dist/utils/credential-policy.d.ts

@@ -21,9 +21,15 @@ export type PolicyAuthorizeInput = {
  * scope grants, derived from the one scope⇄action table so an API-key preset
  * and an OAuth client of the same tier can never drift apart.
  */
-export declare const publishActions: ("teams:read" | "teams:create" | "spaces:read" | "spaces:write" | "spaces:rename" | "domains:read" | "spaces:publish" | "builds:trigger" | "*" | "spaces:create" | "spaces:delete" | "spaces:transfer" | "spaces:export" | "spaces:import" | "spaces:policy.write" | "versions:read" | "versions:promote" | "versions:delete" | "versions:download" | "domains:create" | "domains:verify" | "domains:assign" | "domains:bind" | "domains:delete" | "domains:dns.write" | "domains:dns.credentials.write" | "domains:purchase" | "webhooks:read" | "webhooks:write" | "builds:read" | "builds:create" | "variables:read" | "variables:write" | "tenants:read" | "tenants:write" | "principals:read" | "principals:write" | "infrastructure:read" | "teams:write" | "teams:members.write" | "billing:read" | "billing:write" | "tokens:read" | "tokens:create" | "tokens:revoke" | "runtime:manage")[];
+export declare const publishActions: ("teams:read" | "teams:create" | "teams:members.write" | "spaces:read" | "spaces:write" | "spaces:rename" | "spaces:delete" | "versions:download" | "domains:read" | "connectors:read" | "connectors:write" | "connectors:execute" | "spaces:publish" | "builds:trigger" | "*" | "spaces:create" | "spaces:transfer" | "spaces:export" | "spaces:import" | "spaces:policy.write" | "versions:read" | "versions:promote" | "versions:delete" | "domains:create" | "domains:verify" | "domains:assign" | "domains:bind" | "domains:delete" | "domains:dns.write" | "domains:dns.credentials.write" | "domains:purchase" | "webhooks:read" | "webhooks:write" | "builds:read" | "builds:create" | "variables:read" | "variables:write" | "tenants:read" | "tenants:write" | "principals:read" | "principals:write" | "infrastructure:read" | "teams:write" | "billing:read" | "billing:write" | "tokens:read" | "tokens:create" | "tokens:revoke" | "runtime:manage")[];
 /** The canonical policy resource for a team principal's subtree. */
 export declare function teamResource(input: PolicyCompileInput): string;
+/** The customer-resource collection managed by one marked partner team. */
+export declare function partnerResource(input: PolicyCompileInput): string;
+/** One external customer inside a marked partner team's managed collection. */
+export declare function partnerPrincipalResource(input: PolicyCompileInput & {
+    principalId: string;
+}): string;
 export declare function compileApiKeyPreset(preset: ApiKeyPreset, input: PolicyCompileInput): ApiCredentialPolicy;
 /**
  * Expand a named API-key preset into the finite permissions sent on the public
@@ -38,6 +44,7 @@ export declare function compileTenantRootedPolicy(input: {
 }): ApiCredentialPolicy;
 export declare function compilePartnerPrincipalPolicy(input: {
     tenantId: string;
+    teamId?: string | undefined;
     normalizedPrincipalId: string;
 }): ApiCredentialPolicy;
 export declare function compileTeamRolePolicy(input: PolicyCompileInput & {
@@ -99,5 +106,19 @@ export declare function grantedPrincipalsFromPolicy(policy: ApiCredentialPolicy,
         spaceId: string;
     })[];
 };
+/**
+ * Partner-managed customer collections reached by a policy in one tenant.
+ * A collection grant covers every customer under that team; a principal grant
+ * covers only the named customer. Actions are evaluated separately.
+ */
+export declare function grantedPartnerCollectionsFromPolicy(policy: ApiCredentialPolicy, input: {
+    tenantId: string;
+}): {
+    teamIds: string[];
+    principals: {
+        teamId: string;
+        principalId: string;
+    }[];
+};
 export declare function policyReaches(policy: ApiCredentialPolicy, resourceBase: string): boolean;
 export {};

package/dist/utils/credential-policy.js

@@ -24,6 +24,17 @@ const domainActions = oauthScopeActionsFor("domains:write");
 export function teamResource(input) {
     return `stt://tenant/${input.tenantId}/principal/team/${input.teamId}/*`;
 }
+/** The customer-resource collection managed by one marked partner team. */
+export function partnerResource(input) {
+    return `stt://tenant/${input.tenantId}/partner/${input.teamId}/*`;
+}
+/** One external customer inside a marked partner team's managed collection. */
+export function partnerPrincipalResource(input) {
+    if (input.principalId.includes("*") || input.principalId.includes("/")) {
+        throw new Error("Partner principal id contains a reserved policy character.");
+    }
+    return `stt://tenant/${input.tenantId}/partner/${input.teamId}/principal/${input.principalId}/*`;
+}
 function spaceResource(input) {
     return `stt://tenant/${input.tenantId}/space/${input.spaceId}`;
 }
@@ -65,8 +76,8 @@ function presetActions(preset) {
         case "team_admin":
             return ["*"];
         // The partner tier: everything a partner needs to run its own customers'
-        // spaces on our infrastructure, and nothing that mints credentials, edits
-        // team membership, or moves money.
+        // spaces on our infrastructure, including tenant credentials. Billing and
+        // team membership remain outside partner administration.
         case "partner_admin":
             return [
                 "tenants:read",
@@ -75,12 +86,15 @@ function presetActions(preset) {
                 "principals:write",
                 "infrastructure:read",
                 "spaces:policy.write",
-                ...spaceAdminActions,
+                ...spaceAdminActions.filter((action) => action !== "teams:read"),
                 ...domainActions,
                 "webhooks:read",
                 "webhooks:write",
-                "teams:read",
-                "billing:read",
+                "variables:read",
+                "variables:write",
+                "tokens:read",
+                "tokens:create",
+                "tokens:revoke",
             ];
     }
     throw new Error("Unsupported API key preset.");
@@ -96,6 +110,13 @@ export function compilePartnerPrincipalPolicy(input) {
     if (input.normalizedPrincipalId.includes("*") || input.normalizedPrincipalId.includes("/")) {
         throw new Error("Partner principal id contains a reserved policy character.");
     }
+    const resource = input.teamId
+        ? partnerPrincipalResource({
+            tenantId: input.tenantId,
+            teamId: input.teamId,
+            principalId: input.normalizedPrincipalId,
+        })
+        : `stt://tenant/${input.tenantId}/principal/external/${input.normalizedPrincipalId}/*`;
     return allowPolicy([
         "spaces:read",
         "spaces:create",
@@ -110,7 +131,7 @@ export function compilePartnerPrincipalPolicy(input) {
         "builds:create",
         "variables:read",
         "variables:write",
-    ], [`stt://tenant/${input.tenantId}/principal/external/${input.normalizedPrincipalId}/*`]);
+    ], [resource]);
 }
 export function compileTeamRolePolicy(input) {
     switch (input.role) {
@@ -296,6 +317,34 @@ export function grantedPrincipalsFromPolicy(policy, input) {
         ],
     };
 }
+/**
+ * Partner-managed customer collections reached by a policy in one tenant.
+ * A collection grant covers every customer under that team; a principal grant
+ * covers only the named customer. Actions are evaluated separately.
+ */
+export function grantedPartnerCollectionsFromPolicy(policy, input) {
+    const teamIds = new Set();
+    const principals = new Map();
+    for (const statement of policy.statements) {
+        if (statement.effect !== "allow")
+            continue;
+        for (const resource of statement.resources) {
+            const parsed = parseStatticResource(resource);
+            if (!parsed || (parsed.tenantId !== input.tenantId && parsed.tenantId !== "*"))
+                continue;
+            if (parsed.kind === "partner") {
+                teamIds.add(parsed.teamId);
+            }
+            else if (parsed.kind === "partner-principal") {
+                principals.set(`${parsed.teamId}\0${parsed.principalId}`, {
+                    teamId: parsed.teamId,
+                    principalId: parsed.principalId,
+                });
+            }
+        }
+    }
+    return { teamIds: [...teamIds], principals: [...principals.values()] };
+}
 // Whether the policy's allow statements reach a resource subtree at all. This
 // is a visibility/scoping check (404 vs 403), never an action grant.
 export function policyReaches(policy, resourceBase) {

package/dist/utils/local-space-state.d.ts

@@ -38,6 +38,13 @@ export declare const localSpaceStateSchema: z.ZodObject<{
     pendingOperationId: z.ZodOptional<z.ZodString>;
     lastVersionUrl: z.ZodOptional<z.ZodString>;
     lastSpaceUrl: z.ZodOptional<z.ZodString>;
+    /**
+     * The directory this machine-written link was recorded for, relative (POSIX)
+     * to the checkout root holding it; "." for the root itself. A publish of a
+     * different directory under the same checkout gets its own Space rather than
+     * silently overwriting the one this receipt names.
+     */
+    publishRoot: z.ZodOptional<z.ZodString>;
     /** Secret per-checkout entropy used only to namespace replay-safe first publishes. */
     anonymousPublishNonce: z.ZodOptional<z.ZodString>;
     /** Unsettled first-publish mutation. Retries must reuse this exact key. */

package/dist/utils/local-space-state.js

@@ -50,6 +50,13 @@ export const localSpaceStateSchema = z.strictObject({
     pendingOperationId: z.string().min(1).optional(),
     lastVersionUrl: z.string().min(1).optional(),
     lastSpaceUrl: z.string().min(1).optional(),
+    /**
+     * The directory this machine-written link was recorded for, relative (POSIX)
+     * to the checkout root holding it; "." for the root itself. A publish of a
+     * different directory under the same checkout gets its own Space rather than
+     * silently overwriting the one this receipt names.
+     */
+    publishRoot: z.string().min(1).optional(),
     /** Secret per-checkout entropy used only to namespace replay-safe first publishes. */
     anonymousPublishNonce: z.string().min(32).optional(),
     /** Unsettled first-publish mutation. Retries must reuse this exact key. */

package/dist/utils/logger.d.ts

@@ -0,0 +1,34 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogFields = Record<string, unknown>;
+export type Logger = {
+    debug: (message: string, fields?: LogFields) => void;
+    info: (message: string, fields?: LogFields) => void;
+    warn: (message: string, fields?: LogFields) => void;
+    error: (message: string, fields?: LogFields) => void;
+    child: (bindings: LogFields) => Logger;
+};
+export type LogEmitListener = (level: LogLevel, message: string, fields?: LogFields) => void;
+export type CreateLoggerOptions = {
+    /**
+     * Minimum level to emit; "silent" emits nothing. Defaults to LOG_LEVEL, else
+     * info in production and debug elsewhere.
+     */
+    level?: LogLevel | "silent";
+    /** Output shape. Defaults to json in production (or LOG_FORMAT=json), pretty elsewhere. */
+    format?: "json" | "pretty";
+    /**
+     * Where lines go. "auto" sends debug/info to stdout and warn/error to stderr;
+     * "stderr" sends everything to stderr, for processes whose stdout is a
+     * protocol channel (MCP stdio, CLI --json receipts).
+     */
+    stream?: "auto" | "stderr";
+    /** Bindings merged into every record, as with child(). */
+    bindings?: LogFields;
+    /** Observes every emitted record (e.g. Sentry fan-out). Failures are swallowed. */
+    onEmit?: LogEmitListener;
+    /** Replaces sensitive errors before console output and listener fan-out. */
+    projectError?: (error: Error) => LogFields | undefined;
+};
+export declare function createLogger(options?: CreateLoggerOptions): Logger;
+/** Env-configured logger for processes that own their stdout. */
+export declare const logger: Logger;