@sequenceholdings/artifact-studio 0.8.0 → 0.9.0

package/README.md

@@ -163,6 +163,25 @@ workspace source awaiting a matching SDK release and platform deployment;
 they are not a newly supported public SDK or direct HTTP contract. See
 [VERSION-PIN.md](./VERSION-PIN.md) for compatibility requirements.
 
+Human completion receipts require a genuine Auth0 browser authentication carried
+by the platform. The gateway signs a separate, optional authentication proof
+bound to the exact request context; the server SDK forwards it unchanged.
+Legacy contexts continue to work without producing human receipts. Service mode,
+external ingress, impersonation and an authored `assertedBy` never supply human
+authentication. This proof requires the matching platform and gateway release.
+
+`client.processes.start` accepts an optional `version` selector for a registered
+immutable process version. Omitting it selects the active version. In the
+upcoming SDK 0.8.1, use this selector to start a retained release after the
+active process has been promoted.
+
+The separate `expectedProcess: { version, bundleHash }` option asserts the
+resolved target; it does not select a version. Atlas returns
+`409 PROCESS_IDENTITY_MISMATCH` before creating a run with a different
+definition. Retrying a known run ID compares its persisted definition, so a
+lost response can recover the original run after a process promotion. Current
+process admission and manifest capability checks still apply.
+
 On the request-scoped client returned by `createArtifactServerClient`, declare
 the exact process IDs the application reads or acts on:
 
@@ -350,15 +369,80 @@ until the host rollout completes. Host/session replacement closes the preview.
 
 ## Calling agents from a Next.js server
 
+The upcoming SDK **0.8.1** adds typed, user-mode job admission. Obtain the
+reviewed source tuple with `client.agents.getCurrentIdentity({ kind, id })` and
+pass it as `expectedIdentity` to `createJob` or `createWorkflowJob`, together
+with a stable `idempotencyKey`. An application should retain its reviewed tuple
+and execution intent rather than silently replace a mismatched source with the
+latest definition. The current user's permissions are checked at admission and
+recovery; neither the tuple nor the key grants access.
+
+Declare the exact read routes for current identity and these strict write
+routes in the server manifest:
+
+- `POST /api/agents/jobs/create-idempotent` for `createJob`.
+- `POST /api/agents/workflows/*/jobs` for `createWorkflowJob`.
+
+Keep the same key and semantic request when recovering an uncertain outcome.
+Changed input or source pins under an existing key are refused. A matching
+replay returns the original admission response without resolving a newer source
+head; read the Job separately for its current execution status. These methods use distinct
+strict endpoints so an older host fails before creating a legacy job that
+ignores the idempotency contract. Do not fall back to the legacy create route
+or generate another key merely because an acknowledgement was lost.
+
+`client.agents.getCompletedRun({ agent, runId })` reads a completed response as
+the current user. Declare its `GET /api/agents/jobs/*/completed-response` route
+in `server.capabilities.api.read`. Both the run and private thread must belong
+to that user, and current Agent, Job and Thread read grants remain enforced.
+The bounded response carries JSON output, assistant text and citation resources;
+it omits reasoning, tool inputs and arbitrary tool results. Reused or changed
+conversations, incomplete runs and results over 1,000 messages or 8 MiB fail
+explicitly. Service mode and machine credentials cannot use this method.
+
+`client.agents.captureCompletedRun({ agent, runId })` returns the neutral response
+with a historical `responseHash` and `sourceReceipt`. Explicit
+`client.agents.captureCompletedConversation({ agent, runId })` additionally
+captures permitted user/assistant text and tool inputs/results in
+`response.context`. Declare the respective `completed-source` and
+`completed-conversation` GET routes. Atlas requires current Agent, Job and Thread
+read grants for the actual private source. These user-only captures reject changed
+or unfinished history, recognizable credentials, unverified compaction context
+and responses over 512 KiB. A receipt proves the captured bytes and actual actor;
+receiving functions verify it under their own live evidence capability, and the
+application separately validates its protected source/release association.
+
+`client.agents.captureConversation({ agent, threadId })` explicitly captures a
+sidebar transcript through `GET /api/agents/threads/*/conversation-source`.
+Its response binds a durable settled `revision` and `cutoffAt`, with the same
+permitted `context` and neutral `conversation` metrics. It has no invented agent
+run ID. Active, interrupted or legacy conversations without proven settlement
+are refused. The receiver uses `verifyConversationEvidence` and checks the
+application's protected sidebar/source association before persisting it.
+
+`client.agents.captureCompletedWorkflow({ workflow, runId })` explicitly
+captures a completed standalone Workflow source as an authenticated human with
+current access. The capturing user remains distinct from the original source
+owner recorded in the evidence.
+Declare `GET /api/agents/jobs/*/completed-workflow-source`. The typed response
+contains the persisted merged root output and historical source evidence,
+including real branch outcomes and the original job-admission association;
+it is not an Agent conversation. Current Workflow Invoker and root/child Job
+visibility remain required. Incomplete or changed sources and captures over
+512 KiB fail explicitly. A receiver verifies the historical bytes with its
+separate Workflow evidence capability and checks the application's current
+protected intent; a source receipt grants no current task or write authority.
+
 An application that declares `/api/agents/` in `server.capabilities.api.read`
 and `write` can reach a fixed set of agents API routes as the signed-in user:
 
 | Area | Routes |
 | --- | --- |
 | Chat | `POST chat`, `POST chat/abort`, `GET chat/resume` |
-| Agents | `GET agents`, `GET agents/:id` |
-| Threads | `GET threads`, `POST threads`, `GET threads/:id`, `GET threads/:id/messages`, `PATCH threads/:id/messages/:messageId` |
-| Jobs | `POST jobs`, `GET jobs/:id`, `DELETE jobs/:id` |
+| Agents | `GET agents`, `GET agents/:id`, `GET agents/:id/current-identity` |
+| Threads | `GET threads`, `POST threads`, `GET threads/:id`, `GET threads/:id/messages`, `GET threads/:id/conversation-source`, `PATCH threads/:id/messages/:messageId` |
+| Jobs | `POST jobs`, `POST jobs/create-idempotent`, `GET jobs/:id`, `GET jobs/:id/completed-response`, `GET jobs/:id/completed-source`, `GET jobs/:id/completed-conversation`, `GET jobs/:id/completed-workflow-source`, `DELETE jobs/:id` |
+| Workflows | `GET workflows/:id/current-identity`, `POST workflows/:id/jobs` |
 | Files | `POST files`, `GET files/:id`, `DELETE files/:id`, `GET files/:id/url` |
 
 Atlas answers them with the agents API's own handlers, so agent `can_invoke`,
@@ -416,3 +500,17 @@ streaming and file-transfer helpers retain their ordinary host tracing behavior.
 Tracing does not grant permissions, change service-account behavior or guarantee
 that every transport is instrumented. Traces availability depends on the deployed
 platform version and your app/resource permissions.
+
+
+### Microphone dictation in an isolated application
+
+Explicitly declare browser API read `/api/files/speech/config/get` and write
+`/api/files/speech/stt` to opt an isolated application iframe into microphone
+requests. Both exact paths are required; broad API wildcards do not enable it.
+The browser still asks the user for permission. Existing sandbox origin privileges
+are unchanged, and camera/geolocation remain unavailable. Legacy opaque-origin
+static frames do not receive microphone delegation.
+Upload with `api.upload` option `{ fieldName: 'audio' }`; ordinary uploads still
+default to `file`. Atlas transcription trims silence by default; multipart
+`trimSilence=false` opts out. Speech uses the declared host paths without requiring
+the separate general Next host API rollout flag.

package/dist/api.d.ts

@@ -12,11 +12,12 @@ export declare function getJson<T>({ baseUrl, token, path }: ApiClientOptions &
 export declare function getJsonOr404<T>({ baseUrl, token, path }: ApiClientOptions & {
     path: string;
 }): Promise<T | null>;
-export declare function postJson<T>({ baseUrl, token, path, body, retry503, signal, }: ApiClientOptions & {
+export declare function postJson<T>({ baseUrl, token, path, body, retry503, signal, headers, }: ApiClientOptions & {
     path: string;
     body?: unknown;
     retry503?: boolean;
     signal?: AbortSignal;
+    headers?: Record<string, string>;
 }): Promise<T>;
 export declare function deleteJson({ baseUrl, token, path, signal }: ApiClientOptions & {
     path: string;

package/dist/api.js

@@ -19,7 +19,17 @@ const DEFAULT_RETRY_AFTER_SECONDS = 2;
  * Content-Type) always win over anything here. Malformed JSON is ignored — a
  * bad bypass header should never crash a deploy before the request is even made.
  */
-function extraHeaders() {
+function extraHeaders(baseUrl) {
+    // Preview gateway credentials belong only to the target, never to a separately
+    // authenticated source repository. An unbound header set fails closed.
+    const target = process.env.ARTIFACT_STUDIO_BASE_URL;
+    try {
+        if (!target || new URL(target).origin !== new URL(baseUrl).origin)
+            return {};
+    }
+    catch {
+        return {};
+    }
     const raw = process.env.ARTIFACT_STUDIO_EXTRA_HEADERS?.trim();
     if (!raw)
         return {};
@@ -33,7 +43,7 @@ function extraHeaders() {
             // Prevent case-variant duplicates from being merged by Headers/fetch
             // (e.g. `authorization` + `Authorization` => "a, b"). The client always
             // sets these explicitly below, so ignore any env-supplied variants.
-            if (lower === 'authorization' || lower === 'content-type')
+            if (lower === 'authorization' || lower === 'content-type' || lower === 'x-sequence-source-authorization')
                 continue;
             if (typeof value === 'string')
                 headers[key] = value;
@@ -64,7 +74,7 @@ async function authenticatedFetch({ baseUrl, init = {}, path, token, retry503 =
         ...init,
         redirect: 'manual',
         headers: {
-            ...extraHeaders(),
+            ...extraHeaders(baseUrl),
             ...init.headers,
             Authorization: `Bearer ${token}`,
         },
@@ -84,7 +94,7 @@ export async function getJsonOr404({ baseUrl, token, path }) {
         throw new ArtifactApiError(await responseError('GET', path, response), response.status);
     return response.json();
 }
-export async function postJson({ baseUrl, token, path, body, retry503 = true, signal, }) {
+export async function postJson({ baseUrl, token, path, body, retry503 = true, signal, headers, }) {
     const response = await authenticatedFetch({
         baseUrl,
         token,
@@ -92,7 +102,7 @@ export async function postJson({ baseUrl, token, path, body, retry503 = true, si
         retry503,
         init: {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
+            headers: { ...headers, 'Content-Type': 'application/json' },
             body: body === undefined ? undefined : JSON.stringify(body),
             ...(signal ? { signal } : {}),
         },

package/dist/cli.d.ts

@@ -32,6 +32,8 @@ export declare function getConfiguredDefaultEnv(): Promise<string | undefined>;
  */
 export interface TokenProviderOptions {
     allowInteractiveLogin: boolean;
+    /** A separate source session; omitted for target requests. Never a caller URL. */
+    sourceEnvironment?: string;
 }
 export interface ProvidedToken {
     authMode: SourceAuthMode;

package/dist/cli.js

@@ -3,7 +3,7 @@ import { constants, existsSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getJson, getJsonOr404, postJson } from './api.js';
-import { ENV_URLS, readLocalConfig, resolveEnvironment, writeLocalConfig, } from './config.js';
+import { ENV_URLS, knownEnvUrls, readLocalConfig, resolveEnvironment, writeLocalConfig, } from './config.js';
 import { writeBuildArtifact } from './build.js';
 import { buildArtifactStudioProjectIsolated } from './build-subprocess.js';
 import { resolveArtifactStudioPeerVersions, } from './peer-versions.js';
@@ -33,9 +33,9 @@ const USAGE = `usage:
   seq-studio artifact list --env <env> [--json]
   seq-studio artifact show <slug-or-id> --env <env> [--json]
   seq-studio artifact validate [dir]
-  seq-studio artifact build [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--path <dir>] [--out dist/artifact-bundle.json]
-  seq-studio artifact plan [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--path <dir>] --env <env>
-  seq-studio artifact deploy [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--path <dir>] --env <env> [--skip-unchanged] [--no-create] [--project <id>]
+  seq-studio artifact build [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--path <dir>] [--source-env <env>] [--out dist/artifact-bundle.json]
+  seq-studio artifact plan [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--path <dir>] [--source-env <env>] --env <env>
+  seq-studio artifact deploy [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--path <dir>] [--source-env <env>] --env <env> [--skip-unchanged] [--no-create] [--project <id>]
   seq-studio artifact dev [dir] --env <env> [--once] [--key default] [--link <pkgDir>[,<pkgDir>]] [--port <port>]
   seq-studio artifact promote <deployment-id> --env <env>
   seq-studio artifact pull <project-id> --env <env> --out <dir>
@@ -51,7 +51,7 @@ const USAGE = `usage:
   --repo / --git-url repository (default: its root). The target project comes from
   the source's artifact.bundle.yml project_id.
 
-  Official (active) deploys to deployed environments require \`main\` with a
+  Official (active) deploys require \`main\` (or \`staging\` for staging targets) with a
   resolved git commit and a clean artifact source directory. Dirty files
   outside a nested local source directory are ignored with a warning.
   Deployments targeting \`local\` may use any branch, including dirty working
@@ -61,7 +61,11 @@ const USAGE = `usage:
   Interactive --repo builds clone over smart-HTTP using your seq-studio login
   and repository read access. No PAT is needed. Headless M2M builds use JSON
   materialize and accept only platform-managed --repo sources. Use --env to
-  select the same environment for source and deployment.
+  select the target environment. Next.js build/plan/deploy accept --source-env
+  to read a Git Service repository from a separately authenticated environment.
+  Log in to both environments; source read and target deploy permissions apply.
+  The target must support verified cross-environment builds. Source credentials
+  are used only to fetch source, never passed to the build or stored with it.
 
   Next.js: init --template nextjs, then pnpm install with Node.js 24. dev starts
   a local Next server and an owner-only Atlas preview tunnel (no cloud credentials).
@@ -114,9 +118,9 @@ function validateKnownOptions(args) {
         link: { values: ['env', 'project'], booleans: [] }, env: { values: [], booleans: [] },
         status: { values: ['env'], booleans: [] }, list: { values: ['env'], booleans: ['json'] },
         show: { values: ['env'], booleans: ['json'] }, validate: { values: [], booleans: [] },
-        build: { values: ['env', 'repo', 'git-url', 'ref', 'path', 'out'], booleans: [] },
-        plan: { values: ['env', 'repo', 'git-url', 'ref', 'path'], booleans: [] },
-        deploy: { values: ['env', 'repo', 'git-url', 'ref', 'path', 'project', 'out'], booleans: ['skip-unchanged', 'no-create'] },
+        build: { values: ['source-env', 'env', 'repo', 'git-url', 'ref', 'path', 'out'], booleans: [] },
+        plan: { values: ['source-env', 'env', 'repo', 'git-url', 'ref', 'path'], booleans: [] },
+        deploy: { values: ['source-env', 'env', 'repo', 'git-url', 'ref', 'path', 'project', 'out'], booleans: ['skip-unchanged', 'no-create'] },
         dev: { values: ['env', 'key', 'link', 'port'], booleans: ['once'] },
         promote: { values: ['env'], booleans: [] }, pull: { values: ['env', 'out'], booleans: [] },
         rollback: { values: ['env'], booleans: [] },
@@ -441,16 +445,17 @@ function reportBuildDiagnostics(result) {
 }
 async function buildCommand(args) {
     const spec = parseSourceSpec(args);
+    const sourceEnvironment = sourceEnvironmentFromArgs(args);
     // Local builds stay offline. Public git URLs need no bearer token, but an
     // optional auth lookup still identifies a selected M2M principal so the
     // source policy can reject arbitrary CI input before cloning.
-    const auth = spec.kind === 'git-service'
-        ? await getRequiredAuth(args)
+    const auth = spec.kind === 'git-service' || sourceEnvironment
+        ? await getSourceAuth(args)
         : spec.kind === 'git-url'
             ? await getOptionalAuth(args)
             : null;
     const remote = spec.kind === 'git-service' && auth
-        ? { authMode: auth.authMode, baseUrl: (await envFromArgs(args)).url, token: auth.token }
+        ? { authMode: auth.authMode, baseUrl: (sourceEnvironment ?? await envFromArgs(args)).url, token: auth.token }
         : auth
             ? { authMode: auth.authMode }
             : {};
@@ -459,6 +464,7 @@ async function buildCommand(args) {
         if (isNextArtifactManifest(await readArtifactStudioManifest(source.dir))) {
             return await buildNextCommand({ args, source, active: false });
         }
+        assertSourceEnvironmentSupportsManifest(args);
         const result = await buildPreparedArtifactSource(source);
         reportBuildDiagnostics(result);
         // A remote source's dir is a temp dir we tear down below, so default the
@@ -483,10 +489,12 @@ async function planCommand(args) {
     const auth = await getOptionalAuth(args);
     const token = auth?.token ?? null;
     const spec = parseSourceSpec(args);
+    const sourceEnvironment = sourceEnvironmentFromArgs(args);
+    const sourceAuth = sourceEnvironment ? await getSourceAuth(args) : auth;
     const source = await resolveArtifactSource(spec, {
-        ...(auth ? { authMode: auth.authMode } : {}),
-        baseUrl: env.url,
-        token,
+        ...(sourceAuth ? { authMode: sourceAuth.authMode } : {}),
+        baseUrl: (sourceEnvironment ?? env).url,
+        token: sourceAuth?.token ?? null,
     });
     try {
         const manifest = await readArtifactStudioManifest(source.dir);
@@ -494,6 +502,7 @@ async function planCommand(args) {
             const { planNextProject } = await import('./next-build.js');
             return await planNextProject({ root: source.dir, manifest, environment: env.name });
         }
+        assertSourceEnvironmentSupportsManifest(args);
         const result = await buildPreparedArtifactSource(source);
         reportBuildDiagnostics(result);
         console.log(`[seq-studio] plan ${result.manifest.artifact.project_id} -> ${env.name}`);
@@ -539,10 +548,12 @@ async function deployCommand(args) {
     const { token } = auth;
     const spec = parseSourceSpec(args);
     const explicitProjectId = typeof args.flags.project === 'string' ? args.flags.project : null;
+    const sourceEnvironment = sourceEnvironmentFromArgs(args);
+    const sourceAuth = sourceEnvironment ? await getSourceAuth(args) : auth;
     const source = await resolveArtifactSource(spec, {
-        authMode: auth.authMode,
-        baseUrl: env.url,
-        token,
+        authMode: sourceAuth.authMode,
+        baseUrl: (sourceEnvironment ?? env).url,
+        token: sourceAuth.token,
     });
     try {
         // Fail closed before build / project create for deployed environments.
@@ -558,6 +569,7 @@ async function deployCommand(args) {
         if (isNextArtifactManifest(manifest)) {
             return await buildNextCommand({ args, source, active: true });
         }
+        assertSourceEnvironmentSupportsManifest(args);
         // --skip-unchanged: hash the raw source (no build needed) and no-op when
         // the remote active deployment already matches *and* was built with the
         // same CLI/atlas-ui pin. Lets CI redeploy every artifact on every release
@@ -618,8 +630,10 @@ async function buildNextCommand({ args, source, active }) {
     if (active) {
         assertActiveDeployProvenance({ ...source.provenance, environment: env.name });
     }
-    const repositoryId = active || spec.kind === 'git-service'
-        ? await resolveNextRepositoryId({ spec, repository, baseUrl: env.url, token })
+    const sourceEnvironment = sourceEnvironmentFromArgs(args);
+    const sourceToken = sourceEnvironment ? (await getSourceAuth(args)).token : token;
+    const repositoryId = active || spec.kind === 'git-service' || sourceEnvironment
+        ? await resolveNextRepositoryId({ spec, repository, baseUrl: (sourceEnvironment ?? env).url, token: sourceToken })
         : undefined;
     const project = await ensureRemoteProject({
         env: env.url, token, result: { manifest }, linkConfigDir: spec.kind === 'local' ? source.dir : null,
@@ -632,6 +646,7 @@ async function buildNextCommand({ args, source, active }) {
     return submitNextBuild({
         root: source.dir, sourceRoot: source.sourceRoot, manifest, projectId: project.id, baseUrl: env.url,
         getToken: () => getRequiredToken(args), provenance: source.provenance, repository, repositoryId,
+        ...(sourceEnvironment ? { sourceEnvironment: sourceEnvironment.name, sourceToken } : {}),
         channel: active ? 'active' : 'preview', out: typeof args.flags.out === 'string' ? resolve(args.flags.out) : undefined,
     });
 }
@@ -1027,6 +1042,29 @@ export async function getConfiguredDefaultEnv() {
 async function envFromArgs(args) {
     return resolveEnvironment(typeof args.flags.env === 'string' ? args.flags.env : undefined, await getConfiguredDefaultEnv());
 }
+/** Source selection must never inherit the target URL override. */
+function sourceEnvironmentFromArgs(args) {
+    const name = args.flags['source-env'];
+    if (typeof name !== 'string')
+        return undefined;
+    const url = knownEnvUrls()[name];
+    if (typeof url !== 'string' || !url)
+        throw new Error(`Unknown source environment "${name}". Run seq-studio envs list and login to the source environment.`);
+    return { name, url };
+}
+async function getSourceAuth(args) {
+    const source = sourceEnvironmentFromArgs(args);
+    if (!source)
+        return getRequiredAuth(args);
+    const auth = await resolveAuth({ allowInteractiveLogin: true, sourceEnvironment: source.name });
+    if (!auth)
+        throw new Error(`Authenticate to the source with seq-studio login -e ${source.name}.`);
+    return auth;
+}
+function assertSourceEnvironmentSupportsManifest(args) {
+    if (args.flags['source-env'])
+        throw new Error('--source-env is supported for Next.js repository builds only.');
+}
 let tokenProvider = null;
 export function setTokenProvider(provider) {
     tokenProvider = provider;

package/dist/gateway/authorization-cache.js

@@ -121,7 +121,7 @@ function digest(parts) {
  * bridge values and the cookie's own expiry do not change the decision. */
 export function gatewayAuthorizationKey(session) {
     return digest(['session-v1', session.kind, session.projectId, session.ownerId, session.environment, session.publicOrigin,
-        session.sessionId, session.deploymentId, session.frameworkBuildId, session.published, session.lattice ?? null, session.taskRoutes ?? null]);
+        session.sessionId, session.deploymentId, session.frameworkBuildId, session.published, session.lattice ?? null, session.taskRoutes ?? null, session.authentication ?? null]);
 }
 /** A tunnel credential is keyed by its hash, never retained in the key itself. */
 export function tunnelAuthorizationKey({ token, sessionId, epoch }) {

package/dist/gateway/control.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { TunnelLease } from '../tunnel/index.js';
-import type { GatewaySession } from './session.js';
+import { type GatewaySession } from './session.js';
 import type { GatewayUsageEvent } from './usage.js';
 import { type IngressAuditBatch, type IngressExchangeRequest, type IngressExchangeResponse, type IngressGrantRequest, type IngressGrantResponse, type IngressRevokeRequest, type IngressSnapshot } from '../server/ingress-control-contract.js';
 export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -22,6 +22,10 @@ export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         processId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authentication: z.ZodOptional<z.ZodObject<{
+        method: z.ZodLiteral<"auth0_user">;
+        sub: z.ZodString;
+    }, z.core.$strict>>;
     manifest: z.ZodOptional<z.ZodObject<{
         server: z.ZodObject<{
             resources: z.ZodObject<{
@@ -58,6 +62,10 @@ export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         processId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authentication: z.ZodOptional<z.ZodObject<{
+        method: z.ZodLiteral<"auth0_user">;
+        sub: z.ZodString;
+    }, z.core.$strict>>;
     manifest: z.ZodOptional<z.ZodObject<{
         server: z.ZodObject<{
             resources: z.ZodObject<{
@@ -88,6 +96,10 @@ export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         processId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authentication: z.ZodOptional<z.ZodObject<{
+        method: z.ZodLiteral<"auth0_user">;
+        sub: z.ZodString;
+    }, z.core.$strict>>;
     manifest: z.ZodOptional<z.ZodObject<{
         server: z.ZodObject<{
             resources: z.ZodObject<{

package/dist/gateway/control.js

@@ -1,6 +1,7 @@
 import { createHash, timingSafeEqual } from 'node:crypto';
 import { z } from 'zod';
 import { normalizePublicOrigin } from '../tunnel/protocol.js';
+import { gatewayAuthenticationSchema } from './session.js';
 import { artifactRequestContextSchema } from '../server/request-context.js';
 import { ARTIFACT_NEXT_CONTROL_PATH, artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
 import { untilAborted } from './abort.js';
@@ -13,6 +14,7 @@ const base = {
     capabilities: z.array(id).max(256).default([]), serviceAccountId: id.nullable().default(null),
     lattice: artifactRequestContextSchema.shape.lattice.optional(),
     taskRoutes: artifactRequestContextSchema.shape.taskRoutes,
+    authentication: gatewayAuthenticationSchema.optional(),
     manifest: z.object({ server: z.object({ resources: z.object({
                 concurrency: z.number().int().min(1).max(80), max_instances: z.number().int().min(1).max(100), timeout_seconds: z.number().int().min(1).max(300),
             }) }) }).optional(),
@@ -228,6 +230,7 @@ export class ArtifactGatewayControl {
             published: target.kind !== 'development' && (target.published ?? target.active), bridge,
             ...(target.lattice ? { lattice: target.lattice } : {}),
             ...(target.taskRoutes ? { taskRoutes: target.taskRoutes } : {}),
+            ...(target.authentication ? { authentication: target.authentication } : {}),
         };
         return { session, target };
     }

package/dist/gateway/datadog-startup.d.ts

@@ -0,0 +1,13 @@
+/** Messages contain configuration names, never supplied values or connection errors. */
+export declare class DatadogStartupError extends Error {
+}
+/**
+ * Replaces the sidecar's TCP startup probe only in the opt-in image mode.
+ * The app remains serverless-init's direct child, so its existing signal and
+ * drain handlers still own shutdown. This checks collector startup, not remote
+ * telemetry delivery; the app's /health probe continues to check its own readiness.
+ */
+export declare function waitForDatadogStartup({ env, timeoutMs, }: {
+    env: Record<string, string | undefined>;
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/gateway/datadog-startup.js

@@ -0,0 +1,51 @@
+import { createConnection } from 'node:net';
+import { setTimeout as delay } from 'node:timers/promises';
+/** Messages contain configuration names, never supplied values or connection errors. */
+export class DatadogStartupError extends Error {
+}
+function collectorListening({ port, timeoutMs }) {
+    return new Promise(resolve => {
+        const socket = createConnection({ host: '127.0.0.1', port });
+        let finished = false;
+        const finish = (ready) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(ready);
+        };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+    });
+}
+/**
+ * Replaces the sidecar's TCP startup probe only in the opt-in image mode.
+ * The app remains serverless-init's direct child, so its existing signal and
+ * drain handlers still own shutdown. This checks collector startup, not remote
+ * telemetry delivery; the app's /health probe continues to check its own readiness.
+ */
+export async function waitForDatadogStartup({ env, timeoutMs = 30_000, }) {
+    const mode = env.ARTIFACT_NEXT_DATADOG_IN_CONTAINER;
+    if (mode === undefined || mode === 'false')
+        return;
+    if (mode !== 'true')
+        throw new DatadogStartupError('Invalid ARTIFACT_NEXT_DATADOG_IN_CONTAINER: expected true or false');
+    const configuredPort = env.DD_HEALTH_PORT ?? '5555';
+    const port = Number(configuredPort);
+    if (!/^\d+$/.test(configuredPort) || !Number.isSafeInteger(port) || port < 1 || port > 65535)
+        throw new DatadogStartupError('Invalid DD_HEALTH_PORT: expected an integer from 1 to 65535');
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 30_000)
+        throw new DatadogStartupError('Invalid Datadog startup budget: expected at most 30000 milliseconds');
+    // A monotonic deadline includes both connection attempts and retry delays.
+    const deadline = performance.now() + timeoutMs;
+    while (performance.now() < deadline) {
+        if (await collectorListening({ port, timeoutMs: Math.min(1_000, deadline - performance.now()) }))
+            return;
+        const remaining = deadline - performance.now();
+        if (remaining > 0)
+            await delay(Math.min(100, remaining));
+    }
+    throw new DatadogStartupError('Datadog collector did not become ready within the startup budget');
+}

package/dist/gateway/hosted-proxy.d.ts

@@ -18,6 +18,8 @@ export interface HostedArtifactProxyOptions {
         deploymentId: string;
     };
     requestContext: string;
+    /** Optional actual-human proof generated alongside this exact request context by the gateway. */
+    requestAuthentication?: string;
     /** Admission may inspect a native form prefix and replay it without buffering the body. */
     body?: AsyncIterable<Uint8Array>;
     identityTokenProvider?: (input: {

package/dist/gateway/hosted-proxy.js

@@ -9,6 +9,7 @@ import { createReleaseFormTransform } from '../server/release-forms.js';
 import { declaredContentLength, INGRESS_PROXY_ERROR_CODES, INGRESS_PROXY_LIMITS, writeIngressResponseHead } from './ingress-response.js';
 import { resolveHostedTarget } from './runtime-transport.js';
 import { gatewayElapsedMs } from './usage.js';
+import { ArtifactRequestHeaderError, appendArtifactAuthenticationHeader, assertArtifactRequestHeaderBudget, stripArtifactCloudHeaders, validatedArtifactAuthenticationHeader } from '../server/request-authentication.js';
 export { cloudRunOrigin, resolveHostedTarget } from './runtime-transport.js';
 export const HOSTED_ARTIFACT_PROXY_LIMITS = Object.freeze({ maxRequestBytes: 32 * 1024 * 1024, maxResponseBytes: 32 * 1024 * 1024, timeoutMs: 60_000, maxTimeoutMs: 300_000 });
 const googleAuth = new GoogleAuth();
@@ -40,12 +41,6 @@ async function defaultIdentityTokenProvider({ audience }) {
 export function hostedIdentityToken(input) {
     return defaultIdentityTokenProvider(input);
 }
-function stripCloudHeaders(headers) {
-    for (const name of Object.keys(headers)) {
-        if (name === 'x-serverless-authorization' || name.startsWith('x-goog-'))
-            delete headers[name];
-    }
-}
 /** HTTP-only streaming hop. Authentication, CSRF and release admission happen before calling this. */
 export function proxyHostedArtifact(options) {
     return new HostedExchange(options).run();
@@ -92,11 +87,11 @@ class HostedExchange {
             request.once('error', this.finish);
             this.timer = setTimeout(() => this.fail(504), this.timeoutMs);
             this.timer.unref();
-            void this.prepare().catch(() => this.fail(this.unavailableStatus));
+            void this.prepare().catch(error => this.fail(error instanceof ArtifactRequestHeaderError ? 400 : this.unavailableStatus));
         });
     }
     async prepare() {
-        const { request, response, target, requestContext } = this.options;
+        const { request, response, target, requestContext, requestAuthentication } = this.options;
         const { upstream, audience } = resolveHostedTarget({ target });
         // Cloud Run revision tags select immutable transport destinations, but IAM
         // requires the canonical service audience. Both are control-plane owned;
@@ -107,6 +102,7 @@ class HostedExchange {
             validateHeaderValue('x-sequence-artifact-context', requestContext);
             if (!requestContext || requestContext.length > 16384)
                 throw new Error('Invalid request context');
+            validatedArtifactAuthenticationHeader({ token: requestAuthentication, contextToken: requestContext, external: Boolean(this.options.ingress) });
         }
         catch {
             this.fail(400);
@@ -127,7 +123,9 @@ class HostedExchange {
             this.fail(this.options.ingress ? 400 : 502);
             return;
         }
-        stripCloudHeaders(headers);
+        stripArtifactCloudHeaders({ headers });
+        headers['x-sequence-artifact-context'] = requestContext;
+        appendArtifactAuthenticationHeader({ headers, token: requestAuthentication, contextToken: requestContext });
         if (audience) {
             const provider = this.options.identityTokenProvider ?? defaultIdentityTokenProvider;
             const identityStarted = performance.now();
@@ -147,7 +145,7 @@ class HostedExchange {
         // HTML forms receive release markers. Avoid compression when possible;
         // runtimes that still compress HTML are decoded as a bounded stream below.
         headers['accept-encoding'] = 'identity';
-        headers['x-sequence-artifact-context'] = requestContext;
+        assertArtifactRequestHeaderBudget({ headers });
         const destination = this.resolveDestination(upstream);
         const transport = destination.protocol === 'https:' ? httpsRequest : httpRequest;
         const upstreamStarted = performance.now();
@@ -204,7 +202,7 @@ class HostedExchange {
             // Read before sanitising, which removes content-length as a hop header.
             const declaredLength = declaredContentLength(incoming.headers['content-length']);
             const headers = sanitizeResponseHeaders(incoming.headers);
-            stripCloudHeaders(headers);
+            stripArtifactCloudHeaders({ headers });
             const response = this.options.response;
             if (this.options.ingress) {
                 // Decided on the head, before any body byte; never the HTML release-marker path.

package/dist/gateway/ingress-handler.js

@@ -191,6 +191,8 @@ export function createIngressHandler({ options, runtimeDomain, protocol, isDrain
         };
         response.once('finish', report);
         response.once('close', report);
+        if (response.destroyed)
+            report();
     }
     /** Preflights are answered locally and never forwarded; a refusal carries no CORS headers. */
     function preflight({ request, response, origin, allowed, methods, headers }) {

package/dist/gateway/server.d.ts

@@ -41,7 +41,7 @@ export interface ArtifactGatewayOptions {
 }
 export declare function createArtifactGateway(options: ArtifactGatewayOptions): {
     server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
-    /** Observations recorded but not yet confirmed by Atlas: what a forced exit would lose. */
+    /** Recorded observations not yet confirmed by Atlas; excludes responses still in flight. */
     readonly pendingUsage: number;
     drain(): Promise<void>;
 };