@spacefast/common 0.0.9 → 0.0.11

package/dist/contracts/comments.js

@@ -0,0 +1,200 @@
+import { z } from "zod";
+import { CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
+export const collaborationModeSchema = z.enum(["review"]);
+export const commentThreadStatusSchema = z.enum(["open", "archived"]);
+// The space access levels capability follows (SPACEFAST-CAST-PLAN D-2). Invited
+// reviewers are space invitees with one of these levels; the on-page overlay and
+// inbox re-evaluate the effective level server-side at join — this is only the
+// stored grant the dashboard manages.
+export const collaborationReviewerLevelSchema = z.enum(["viewer", "commenter", "editor"]);
+// An invited reviewer: a person (by email) granted a level on the space's review
+// surface. Kept in settingsJson so adding/removing reviewers never requires a
+// republish (read from the ETag'd overlay-config, SPACEFAST-CAST-PLAN §4.2).
+export const collaborationInvitedReviewerSchema = z.object({
+    email: z.string().email(),
+    level: collaborationReviewerLevelSchema,
+});
+export const collaborationSettingsSchema = z
+    .object({
+    anonymousReviewers: z.boolean().optional(),
+    publishedAnonymousCommenters: z.boolean().optional(),
+    invitedReviewers: z.array(collaborationInvitedReviewerSchema).optional(),
+    // Whether comments are surfaced on the live/published host (vs preview-only).
+    // The published loader (SPACEFAST-CAST-PLAN §4.2) mounts the orb on a live
+    // host only when this is true; toggling it never requires a republish — the
+    // always-injected inert tag reads behavior from the ETag'd overlay-config.
+    publishedComments: z.boolean().optional(),
+    allowedOrigins: z.array(z.string().min(1)).optional(),
+    notificationPreferences: z
+        .object({
+        newThreads: z.boolean().default(true),
+        newReplies: z.boolean().default(true),
+        statusChanges: z.boolean().default(true),
+    })
+        .partial()
+        .optional(),
+})
+    .catchall(z.unknown());
+export const collaborationSchema = z.object({
+    spaceId: z.string(),
+    enabled: z.boolean(),
+    mode: collaborationModeSchema,
+    castResourceId: z.string().nullable(),
+    castResourceKey: z.string().nullable(),
+    settings: collaborationSettingsSchema,
+    createdAt: z.string().datetime().nullable(),
+    updatedAt: z.string().datetime().nullable(),
+});
+export const collaborationUpdateSchema = z.object({
+    enabled: z.boolean(),
+    mode: collaborationModeSchema.optional(),
+    settings: collaborationSettingsSchema.optional(),
+});
+export const collaborationTokenRequestSchema = z.object({
+    versionId: z.string().min(1).optional(),
+    pagePath: z.string().min(1).default("/"),
+    displayName: z.string().min(1).max(120).optional(),
+});
+export const collaborationTokenResponseSchema = z.object({
+    token: z.string(),
+    expiresAt: z.string().datetime(),
+    cast: z.object({
+        resource: z.string(),
+        room: z.string().nullable(),
+    }),
+});
+export const collaborationHandoffRequestSchema = z.object({
+    versionId: z.string().min(1),
+    pagePath: z.string().min(1).default("/"),
+});
+export const collaborationHandoffResponseSchema = z.object({
+    handoffToken: z.string(),
+    expiresAt: z.string().datetime(),
+    url: z.string().url().nullable(),
+});
+export const collaborationHandoffExchangeSchema = z.object({
+    handoffToken: z.string().min(16),
+});
+export const realtimeTokenRequestSchema = z.object({
+    versionId: z.string().optional(),
+    scope: z.enum(["space", "version"]).default("space"),
+});
+export const realtimeTokenResponseSchema = z.object({
+    token: z.string(),
+    expiresAt: z.string().datetime(),
+    cast: z.object({
+        resource: z.string(),
+        room: z.string(),
+        loaderUrl: z.string().url(),
+    }),
+});
+export const noticePublishSchema = z.object({
+    versionId: z.string().optional(),
+    kind: z.string().min(1).max(80).default("version.ready"),
+    title: z.string().min(1).max(160),
+    message: z.string().min(1).max(2_000),
+    level: z.enum(["info", "success", "warning", "error"]).default("info"),
+    payload: z.record(z.string(), z.unknown()).optional(),
+    durable: z.boolean().default(true),
+    idempotencyKey: z.string().min(1).max(320).optional(),
+});
+export const noticePublishResponseSchema = z.object({
+    status: z.string(),
+    event: z.record(z.string(), z.unknown()).nullable(),
+    broadcast: z.record(z.string(), z.unknown()).nullable(),
+});
+export const collabOverlayConfigQuerySchema = z.object({
+    path: z.string().min(1).optional(),
+    versionId: z.string().min(1).optional(),
+    host: z.string().min(1).optional(),
+});
+// Snake case is intentional: the injected Collab SDK consumes this alongside
+// Cast's snake-case join payload without a remapping layer.
+export const collabOverlayConfigSchema = z.object({
+    enabled: z.boolean(),
+    anonymous_commenters: z.boolean(),
+    resource_key: z.string().nullable(),
+    room_key: z.string().nullable(),
+    version: z.object({
+        id: z.string().nullable(),
+        current: z.string().nullable(),
+    }),
+    ws_url: z.string().nullable(),
+    endpoints: z.object({
+        token: z.string().url(),
+        handoff_exchange: z.string().url(),
+        auth_bridge: z.string().url(),
+        screenshots: z.string().url(),
+    }),
+    features: z.object({
+        drawing: z.boolean(),
+        capture: z.boolean(),
+        notices: z.boolean(),
+    }),
+});
+export const commentAuthorSchema = z.object({
+    kind: z.string().nullable(),
+    id: z.string().nullable(),
+    name: z.string().nullable(),
+});
+export const commentTargetSchema = z.record(z.string(), z.unknown()).nullable();
+export const commentThreadSchema = z.object({
+    id: z.string(),
+    castThreadId: z.string(),
+    spaceId: z.string(),
+    versionId: z.string().nullable(),
+    channel: z.string().nullable(),
+    pagePath: z.string(),
+    url: z.string().nullable(),
+    status: commentThreadStatusSchema,
+    unread: z.boolean(),
+    unreadCount: z.number().int().min(0),
+    body: z.string().nullable(),
+    author: commentAuthorSchema.nullable(),
+    target: commentTargetSchema,
+    comments: z.array(z.record(z.string(), z.unknown())),
+    permalink: z.string().nullable(),
+    updatedAt: z.string().datetime().nullable(),
+});
+export const commentListQuerySchema = cursorListQuerySchema.extend({
+    versionId: z.string().optional(),
+    status: commentThreadStatusSchema.optional(),
+    pagePath: z.string().optional(),
+});
+export const commentCreateSchema = z.object({
+    pagePath: z.string().min(1).default("/"),
+    body: z.string().min(1).max(16_000),
+    target: commentTargetSchema.optional(),
+    idempotencyKey: z.string().min(1).max(320).optional(),
+});
+export const commentScreenshotCreateSchema = z.object({
+    versionId: z.string().min(1),
+    pagePath: z.string().min(1).default("/"),
+    contentType: z.enum(["image/png", "image/jpeg", "image/webp"]),
+    contentBase64: z.string().min(1),
+});
+export const commentScreenshotSchema = z.object({
+    id: z.string(),
+    key: z.string(),
+    url: z.string().url(),
+    expiresAt: z.string().datetime(),
+});
+export const commentReplySchema = z.object({
+    body: z.string().min(1).max(16_000),
+    idempotencyKey: z.string().min(1).max(320).optional(),
+});
+export const commentPatchSchema = z.object({
+    status: commentThreadStatusSchema.optional(),
+});
+export const commentExportQuerySchema = z.object({
+    format: z.enum(["markdown", "json"]).default("markdown"),
+    status: commentThreadStatusSchema.optional(),
+});
+export const commentListResponseSchema = z.object({
+    data: z.array(commentThreadSchema),
+    pagination: CursorPaginationSchema,
+});
+export const commentExportResponseSchema = z.object({
+    format: z.enum(["markdown", "json"]),
+    content: z.string(),
+});

package/dist/contracts/device-auth.d.ts

@@ -1,4 +1,6 @@
 import { z } from "zod";
+export { DeviceTeamScopeSchema } from "./device-team-scope.js";
+export type { DeviceTeamScope } from "./device-team-scope.js";
 export declare const DeviceAuthorizationStartRequestSchema: z.ZodObject<{
     clientId: z.ZodDefault<z.ZodString>;
     scope: z.ZodOptional<z.ZodString>;
@@ -64,6 +66,7 @@ export declare const DeviceAuthorizationPollResponseSchema: z.ZodObject<{
             team_admin: "team_admin";
             billing_viewer: "billing_viewer";
         }>>;
+        teamScope: z.ZodNullable<z.ZodType<import("./device-team-scope.js").DeviceTeamScope, unknown, z.core.$ZodTypeInternals<import("./device-team-scope.js").DeviceTeamScope, unknown>>>;
         policy: z.ZodNullable<z.ZodObject<{
             version: z.ZodLiteral<"2026-06-09">;
             statements: z.ZodArray<z.ZodObject<{
@@ -163,7 +166,8 @@ export declare const DeviceAuthorizationVerifyResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const DeviceAuthorizationApproveRequestSchema: z.ZodObject<{
     userCode: z.ZodString;
-    teamId: z.ZodString;
+    teams: z.ZodType<import("./device-team-scope.js").DeviceTeamScope, unknown, z.core.$ZodTypeInternals<import("./device-team-scope.js").DeviceTeamScope, unknown>>;
+    claimTeamId: z.ZodOptional<z.ZodString>;
     preset: z.ZodEnum<{
         ci_deploy: "ci_deploy";
         space_publisher: "space_publisher";
@@ -185,3 +189,219 @@ export declare const DeviceAuthorizationDenyRequestSchema: z.ZodObject<{
 export declare const DeviceAuthorizationDenyResponseSchema: z.ZodObject<{
     status: z.ZodLiteral<"denied">;
 }, z.core.$strip>;
+export declare const AGENT_HANDOFF_CLIENT_TARGETS: readonly ["claude-code", "codex", "cursor", "vscode"];
+export type AgentHandoffClientTarget = (typeof AGENT_HANDOFF_CLIENT_TARGETS)[number];
+export declare const AgentHandoffCreateRequestSchema: z.ZodObject<{
+    teamId: z.ZodString;
+    spaceId: z.ZodString;
+    clientTargetId: z.ZodEnum<{
+        "claude-code": "claude-code";
+        cursor: "cursor";
+        vscode: "vscode";
+        codex: "codex";
+    }>;
+}, z.core.$strict>;
+export type AgentHandoffCreateRequest = z.infer<typeof AgentHandoffCreateRequestSchema>;
+export declare const AgentHandoffCreateResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    url: z.ZodString;
+    expiresAt: z.ZodString;
+    teamId: z.ZodString;
+    spaceId: z.ZodString;
+    clientTargetId: z.ZodEnum<{
+        "claude-code": "claude-code";
+        cursor: "cursor";
+        vscode: "vscode";
+        codex: "codex";
+    }>;
+}, z.core.$strict>;
+export type AgentHandoffCreateResponse = z.infer<typeof AgentHandoffCreateResponseSchema>;
+export declare const AgentHandoffRedeemRequestSchema: z.ZodObject<{
+    url: z.ZodString;
+    clientTargetId: z.ZodOptional<z.ZodEnum<{
+        "claude-code": "claude-code";
+        cursor: "cursor";
+        vscode: "vscode";
+        codex: "codex";
+    }>>;
+}, z.core.$strict>;
+export type AgentHandoffRedeemRequest = z.infer<typeof AgentHandoffRedeemRequestSchema>;
+export declare const AgentHandoffRedeemResponseSchema: z.ZodObject<{
+    status: z.ZodLiteral<"redeemed">;
+    apiKey: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        tenantId: z.ZodNullable<z.ZodString>;
+        subject: z.ZodNullable<z.ZodObject<{
+            type: z.ZodEnum<{
+                team: "team";
+                external: "external";
+                system: "system";
+                user: "user";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strip>>;
+        ownerPrincipal: z.ZodNullable<z.ZodObject<{
+            type: z.ZodEnum<{
+                team: "team";
+                external: "external";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strip>>;
+        createdByUserId: z.ZodString;
+        preset: z.ZodNullable<z.ZodEnum<{
+            ci_deploy: "ci_deploy";
+            space_publisher: "space_publisher";
+            space_admin: "space_admin";
+            site_admin: "site_admin";
+            domain_manager: "domain_manager";
+            team_admin: "team_admin";
+            billing_viewer: "billing_viewer";
+        }>>;
+        teamScope: z.ZodNullable<z.ZodType<import("./device-team-scope.js").DeviceTeamScope, unknown, z.core.$ZodTypeInternals<import("./device-team-scope.js").DeviceTeamScope, unknown>>>;
+        policy: z.ZodNullable<z.ZodObject<{
+            version: z.ZodLiteral<"2026-06-09">;
+            statements: z.ZodArray<z.ZodObject<{
+                effect: z.ZodEnum<{
+                    allow: "allow";
+                    deny: "deny";
+                }>;
+                actions: z.ZodArray<z.ZodEnum<{
+                    "*": "*";
+                    "sites:read": "sites:read";
+                    "sites:create": "sites:create";
+                    "sites:write": "sites:write";
+                    "sites:delete": "sites:delete";
+                    "sites:policy.write": "sites:policy.write";
+                    "spaces:read": "spaces:read";
+                    "spaces:create": "spaces:create";
+                    "spaces:write": "spaces:write";
+                    "spaces:delete": "spaces:delete";
+                    "spaces:publish": "spaces:publish";
+                    "spaces:transfer": "spaces:transfer";
+                    "spaces:export": "spaces:export";
+                    "spaces:import": "spaces:import";
+                    "versions:read": "versions:read";
+                    "versions:promote": "versions:promote";
+                    "versions:delete": "versions:delete";
+                    "versions:download": "versions:download";
+                    "domains:read": "domains:read";
+                    "domains:create": "domains:create";
+                    "domains:verify": "domains:verify";
+                    "domains:assign": "domains:assign";
+                    "domains:bind": "domains:bind";
+                    "domains:delete": "domains:delete";
+                    "domains:dns.write": "domains:dns.write";
+                    "domains:dns.credentials.write": "domains:dns.credentials.write";
+                    "domains:purchase": "domains:purchase";
+                    "webhooks:read": "webhooks:read";
+                    "webhooks:write": "webhooks:write";
+                    "builds:read": "builds:read";
+                    "builds:create": "builds:create";
+                    "teams:read": "teams:read";
+                    "teams:write": "teams:write";
+                    "teams:members.write": "teams:members.write";
+                    "billing:read": "billing:read";
+                    "billing:write": "billing:write";
+                    "tokens:read": "tokens:read";
+                    "tokens:create": "tokens:create";
+                    "tokens:revoke": "tokens:revoke";
+                    "mcp:tools": "mcp:tools";
+                    "runtime:manage": "runtime:manage";
+                }>>;
+                resources: z.ZodArray<z.ZodString>;
+                conditions: z.ZodOptional<z.ZodObject<{
+                    "request.client": z.ZodOptional<z.ZodEnum<{
+                        api: "api";
+                        dashboard: "dashboard";
+                        cli: "cli";
+                        worker: "worker";
+                    }>>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        secretPreview: z.ZodString;
+        secret: z.ZodOptional<z.ZodString>;
+        notBefore: z.ZodNullable<z.ZodString>;
+        expiresAt: z.ZodNullable<z.ZodString>;
+        ipAllowlist: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        revokedAt: z.ZodNullable<z.ZodString>;
+        enabled: z.ZodBoolean;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        lastRequestAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    teamId: z.ZodString;
+    spaceId: z.ZodString;
+    clientTargetId: z.ZodEnum<{
+        "claude-code": "claude-code";
+        cursor: "cursor";
+        vscode: "vscode";
+        codex: "codex";
+    }>;
+}, z.core.$strict>;
+export type AgentHandoffRedeemResponse = z.infer<typeof AgentHandoffRedeemResponseSchema>;
+export declare const AgentHandoffRevokeResponseSchema: z.ZodObject<{
+    status: z.ZodLiteral<"revoked">;
+}, z.core.$strict>;
+export type AgentHandoffRevokeResponse = z.infer<typeof AgentHandoffRevokeResponseSchema>;
+export declare const AgentHandoffListQuerySchema: z.ZodObject<{
+    teamId: z.ZodString;
+}, z.core.$strip>;
+export type AgentHandoffListQuery = z.infer<typeof AgentHandoffListQuerySchema>;
+export declare const AgentHandoffStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    revoked: "revoked";
+    redeemed: "redeemed";
+}>;
+export declare const AgentHandoffSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    teamId: z.ZodString;
+    spaceId: z.ZodString;
+    clientTargetId: z.ZodEnum<{
+        "claude-code": "claude-code";
+        cursor: "cursor";
+        vscode: "vscode";
+        codex: "codex";
+    }>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        revoked: "revoked";
+        redeemed: "redeemed";
+    }>;
+    createdAt: z.ZodString;
+    expiresAt: z.ZodString;
+    redeemedAt: z.ZodNullable<z.ZodString>;
+    revokedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type AgentHandoffSummary = z.infer<typeof AgentHandoffSummarySchema>;
+export declare const AgentHandoffListResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    teamId: z.ZodString;
+    spaceId: z.ZodString;
+    clientTargetId: z.ZodEnum<{
+        "claude-code": "claude-code";
+        cursor: "cursor";
+        vscode: "vscode";
+        codex: "codex";
+    }>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        revoked: "revoked";
+        redeemed: "redeemed";
+    }>;
+    createdAt: z.ZodString;
+    expiresAt: z.ZodString;
+    redeemedAt: z.ZodNullable<z.ZodString>;
+    revokedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>>;
+export type AgentHandoffListResponse = z.infer<typeof AgentHandoffListResponseSchema>;
+export declare const AgentHandoffDeclineReasonSchema: z.ZodEnum<{
+    expired: "expired";
+    revoked: "revoked";
+    invalid_handoff: "invalid_handoff";
+    already_redeemed: "already_redeemed";
+    client_mismatch: "client_mismatch";
+    origin_mismatch: "origin_mismatch";
+}>;

package/dist/contracts/device-auth.js

@@ -1,5 +1,8 @@
 import { z } from "zod";
+import { AGENT_HANDOFF_DECLINE_REASONS } from "../docs/agent-setup.js";
 import { ApiKeyPresetSchema, ApiKeySchema } from "./api-keys.js";
+import { DeviceTeamScopeSchema } from "./device-team-scope.js";
+export { DeviceTeamScopeSchema } from "./device-team-scope.js";
 // Device authorization flow (internal-docs/platform.md Credential Bootstrap):
 // `POST /v1/auth/device` starts the flow, `POST /v1/auth/device/poll` redeems
 // it. Device codes are bearer capabilities: they ride POST bodies only, are
@@ -120,8 +123,8 @@ export const DeviceAuthorizationVerifyResponseSchema = z.object({
         .describe("Explicit claim handoff attached to this device authorization, if any."),
 });
 // Approval intent (`POST /v1/auth/device/approve`): the approver chooses the
-// team and preset. If the device start request carried a claim handoff, approval
-// also claims that anonymous space into the chosen team after the approval CAS
+// team scope and preset. If the device start request carried a claim handoff,
+// approval also claims that anonymous space into the explicit destination team after the approval CAS
 // wins. The intent persists server-side and the poll mints from it; the chosen
 // preset's compiled policy must be a subset of the approver's effective
 // team-role policy.
@@ -133,10 +136,12 @@ export const DeviceAuthorizationApproveRequestSchema = z
         .min(1)
         .max(32)
         .describe("User code shown on the device being approved (dashes ignored)."),
-    teamId: z
+    teams: DeviceTeamScopeSchema.describe("Team access granted to the device: all current and future memberships, an explicit non-empty team list, or sign-in-only access."),
+    claimTeamId: z
         .string()
         .min(1)
-        .describe("Team the minted API key will belong to. The approver must be a member."),
+        .optional()
+        .describe("Explicit destination team for a claim handoff. Required when the flow carries a claim."),
     preset: ApiKeyPresetSchema.describe("Policy preset for the minted key. Its compiled policy must be a subset of the approver's team-role policy."),
     agentContinuation: z
         .boolean()
@@ -164,3 +169,100 @@ export const DeviceAuthorizationDenyRequestSchema = z.object({
 export const DeviceAuthorizationDenyResponseSchema = z.object({
     status: z.literal("denied").describe("The device authorization is denied."),
 });
+export const AGENT_HANDOFF_CLIENT_TARGETS = ["claude-code", "codex", "cursor", "vscode"];
+export const AgentHandoffCreateRequestSchema = z
+    .object({
+    teamId: z.string().min(1).describe("Team that owns the selected Space."),
+    spaceId: z.string().min(1).describe("Finite Space scope granted to the agent."),
+    clientTargetId: z
+        .enum(AGENT_HANDOFF_CLIENT_TARGETS)
+        .describe("CLI-redeemable client family the handoff is bound to."),
+})
+    .strict();
+export const AgentHandoffCreateResponseSchema = z
+    .object({
+    id: z.string().min(1).describe("Opaque app-private handoff document identifier."),
+    url: z
+        .string()
+        .url()
+        .describe("Sensitive one-time handoff URL. This is the only response field containing the fragment secret."),
+    expiresAt: z
+        .string()
+        .datetime()
+        .describe("Instant after which the handoff cannot be redeemed."),
+    teamId: z.string().min(1).describe("Team that owns the selected Space."),
+    spaceId: z.string().min(1).describe("Finite Space scope granted to the agent."),
+    clientTargetId: z
+        .enum(AGENT_HANDOFF_CLIENT_TARGETS)
+        .describe("CLI-redeemable client family the handoff is bound to."),
+})
+    .strict();
+export const AgentHandoffRedeemRequestSchema = z
+    .object({
+    url: z
+        .string()
+        .min(1)
+        .describe("Full sensitive handoff link, supplied only in the request body."),
+    clientTargetId: z
+        .enum(AGENT_HANDOFF_CLIENT_TARGETS)
+        .optional()
+        .describe("Declared redeeming client family, when the client can identify itself."),
+})
+    .strict();
+export const AgentHandoffRedeemResponseSchema = z
+    .object({
+    status: z.literal("redeemed").describe("The handoff was redeemed exactly once."),
+    apiKey: ApiKeySchema.describe("Finite Space-scoped API key including its one-time secret."),
+    teamId: z.string().min(1).describe("Team that owns the selected Space."),
+    spaceId: z.string().min(1).describe("Finite Space scope granted to the agent."),
+    clientTargetId: z
+        .enum(AGENT_HANDOFF_CLIENT_TARGETS)
+        .describe("CLI-redeemable client family the handoff is bound to."),
+})
+    .strict();
+export const AgentHandoffRevokeResponseSchema = z
+    .object({
+    status: z.literal("revoked").describe("The unused handoff is revoked."),
+})
+    .strict();
+// List (`GET /v1/auth/agent-handoffs?teamId=…`): the human handoff ledger. Session-only,
+// scoped to one team, bounded to the newest rows (active handoffs are few and short-lived,
+// so the bound can never hide a revocable link); rows are the truthful lifecycle record,
+// never the secret (the fragment secret exists only in the one create response and is
+// never listed or replayed).
+export const AgentHandoffListQuerySchema = z.object({
+    teamId: z.string().min(1).describe("Team whose issued agent handoffs to list."),
+});
+export const AgentHandoffStatusSchema = z
+    .enum(["pending", "redeemed", "revoked"])
+    .describe("Stored lifecycle status. `expired` is not a stored status — it is derived by the caller from `expiresAt`.");
+export const AgentHandoffSummarySchema = z
+    .object({
+    id: z.string().min(1).describe("Opaque app-private handoff document identifier."),
+    teamId: z.string().min(1).describe("Team that owns the selected Space."),
+    spaceId: z.string().min(1).describe("Finite Space scope granted to the agent."),
+    clientTargetId: z
+        .enum(AGENT_HANDOFF_CLIENT_TARGETS)
+        .describe("CLI-redeemable client family the handoff is bound to."),
+    status: AgentHandoffStatusSchema,
+    createdAt: z.string().datetime().describe("Instant the handoff was minted."),
+    expiresAt: z
+        .string()
+        .datetime()
+        .describe("Instant after which the handoff cannot be redeemed."),
+    redeemedAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .describe("Instant the handoff was redeemed, if it was."),
+    revokedAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .describe("Instant the handoff was revoked, if it was."),
+})
+    .strict();
+export const AgentHandoffListResponseSchema = z.array(AgentHandoffSummarySchema);
+export const AgentHandoffDeclineReasonSchema = z
+    .enum(AGENT_HANDOFF_DECLINE_REASONS)
+    .describe("Terminal reason an authenticated handoff exchange was declined.");

package/dist/contracts/device-team-scope.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export type DeviceTeamScope = {
+    mode: "all";
+} | {
+    mode: "teams";
+    teamIds: string[];
+} | {
+    mode: "none";
+};
+export declare const DeviceTeamScopeSchema: z.ZodType<DeviceTeamScope>;

package/dist/contracts/device-team-scope.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export const DeviceTeamScopeSchema = z.discriminatedUnion("mode", [
+    z.object({ mode: z.literal("all") }).strict(),
+    z
+        .object({
+        mode: z.literal("teams"),
+        teamIds: z
+            .array(z.string().min(1))
+            .min(1)
+            .max(100)
+            .refine((teamIds) => new Set(teamIds).size === teamIds.length, {
+            message: "teamIds must be unique.",
+        }),
+    })
+        .strict(),
+    z.object({ mode: z.literal("none") }).strict(),
+]);