@sequenceholdings/artifact-studio 0.5.0 → 0.6.2

package/dist/server/ingress-routes.js

@@ -0,0 +1,150 @@
+import { isManagedServerInvokePath } from './managed-server-path.js';
+/**
+ * Inbound route grammar for an Artifact Next external ingress (design §(a) "Paths").
+ *
+ * One module owns the three steps every component must agree on: the gateway canonicalises the
+ * raw request target and matches it, Atlas re-matches the signed path on the active manifest, and
+ * the SDK binds the context to the route it serves. The static wildcard matcher
+ * (`manifest-static.ts`) is deliberately not used: it prefix-matches, and a route must not.
+ */
+export const INGRESS_ROUTE_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+/** Longest raw request target the canonicaliser looks at, the signed context path's own cap. */
+export const MAX_INGRESS_PATH_LENGTH = 8192;
+const MAX_TEMPLATE_LENGTH = 512;
+/** A request-time placeholder value: one segment, never `.` or `..`, no encoding. */
+const PLACEHOLDER_VALUE = /^(?!\.{1,2}$)[A-Za-z0-9._~-]{1,128}$/;
+const PLACEHOLDER_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+// Characters the signed context path refuses, or that a request target can only carry by mistake.
+const FORBIDDEN_TARGET_CHARACTERS = /[\\#\s\x00-\x1f\x7f]/;
+/**
+ * Canonicalises a raw origin-form request target (`/path?query`). Returns `null`, so the caller
+ * answers 404, when the pathname is not already canonical: it differs from what the URL parser
+ * makes of it, contains an empty, `.` or `..` segment (a trailing slash is an empty segment), or
+ * contains `%`; or when the query is not already in the form the URL parser serializes it to.
+ * The query string is never used for matching and is returned verbatim.
+ */
+export function canonicalizeIngressPath(raw) {
+    if (typeof raw !== 'string' || raw.length === 0 || raw.length > MAX_INGRESS_PATH_LENGTH)
+        return null;
+    if (FORBIDDEN_TARGET_CHARACTERS.test(raw))
+        return null;
+    const separator = raw.indexOf('?');
+    const path = separator === -1 ? raw : raw.slice(0, separator);
+    const query = separator === -1 ? '' : raw.slice(separator + 1);
+    if (!path.startsWith('/') || path.startsWith('//') || path.includes('%'))
+        return null;
+    let url;
+    try {
+        url = new URL(raw, 'http://ingress.invalid');
+    }
+    catch {
+        return null;
+    }
+    if (url.pathname !== path)
+        return null;
+    // A handler sees only the URL parser's serialization of the query (NextRequest builds a URL), so a
+    // raw query the parser would re-encode yields a signed path the handler can never reproduce.
+    if (url.search.replace(/^\?/, '') !== query)
+        return null;
+    if (!path.slice(1).split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..'))
+        return null;
+    return { path, query };
+}
+/** The single string the gateway signs, Atlas re-matches and the SDK binds: path plus raw query. */
+export function signedIngressPath({ path, query }) {
+    return query === '' ? path : `${path}?${query}`;
+}
+/**
+ * Parses a declared route template such as `/api/borrower/documents/{documentId}/notes`.
+ * Literal segments use the Lattice `managed_server` path grammar; a `{name}` placeholder is a
+ * whole segment. Returns `null` for anything else: no `/api/` prefix, a wildcard, `%`, a query,
+ * a trailing slash, an empty, `.` or `..` segment, or a repeated placeholder name.
+ */
+export function parseRouteTemplate(template) {
+    if (typeof template !== 'string' || template.length > MAX_TEMPLATE_LENGTH)
+        return null;
+    if (!template.startsWith('/api/') || /[*%?#]/.test(template))
+        return null;
+    const names = new Set();
+    const segments = [];
+    for (const segment of template.slice(1).split('/')) {
+        const placeholder = /^\{([^{}]*)\}$/.exec(segment);
+        if (placeholder) {
+            const name = placeholder[1];
+            if (!PLACEHOLDER_NAME.test(name) || names.has(name))
+                return null;
+            names.add(name);
+            segments.push({ kind: 'placeholder', name });
+        }
+        else {
+            if (!isManagedServerInvokePath(`/${segment}`))
+                return null;
+            segments.push({ kind: 'literal', value: segment });
+        }
+    }
+    return { template, segments };
+}
+export function ingressRouteId({ method, template }) {
+    return `${method} ${template}`;
+}
+function matchTemplate(parsed, parts) {
+    if (parsed.segments.length !== parts.length)
+        return null;
+    // No prototype: a lookup of a name the route does not declare is undefined, never an inherited function.
+    const params = Object.create(null);
+    for (const [index, segment] of parsed.segments.entries()) {
+        const part = parts[index];
+        if (segment.kind === 'literal') {
+            if (segment.value !== part)
+                return null;
+        }
+        else {
+            if (!PLACEHOLDER_VALUE.test(part))
+                return null;
+            params[segment.name] = part;
+        }
+    }
+    return params;
+}
+/**
+ * Exact-matches a method and a canonical pathname (from `canonicalizeIngressPath(...).path`, never
+ * the query) against declared routes. Methods compare exactly. An unparseable declaration never
+ * matches, and a path that two declarations both match returns `null`: the manifest refuses
+ * overlapping routes, so ambiguity here means the declarations did not come from a valid manifest.
+ */
+export function matchIngressRoute(routes, method, canonicalPath) {
+    if (!INGRESS_ROUTE_METHODS.includes(method))
+        return null;
+    const canonical = canonicalizeIngressPath(canonicalPath);
+    if (!canonical || canonical.query !== '' || canonicalPath.includes('?'))
+        return null;
+    const parts = canonical.path.slice(1).split('/');
+    let found = null;
+    for (const route of routes) {
+        if (!route.methods.includes(method))
+            continue;
+        const parsed = parseRouteTemplate(route.path);
+        if (!parsed)
+            continue;
+        const params = matchTemplate(parsed, parts);
+        if (!params)
+            continue;
+        if (found)
+            return null;
+        found = { routeId: ingressRouteId({ method, template: route.path }), params: Object.freeze(params), route };
+    }
+    return found;
+}
+/**
+ * Whether one request path could match both templates: same segment count, and at every position
+ * either equal literals or at least one placeholder. Conservative: a placeholder is treated as
+ * matching any literal opposite it.
+ */
+export function ingressRouteTemplatesOverlap({ left, right }) {
+    if (left.segments.length !== right.segments.length)
+        return false;
+    return left.segments.every((segment, index) => {
+        const other = right.segments[index];
+        return segment.kind === 'placeholder' || other.kind === 'placeholder' || segment.value === other.value;
+    });
+}

package/dist/server/internal/signed-token.d.ts

@@ -0,0 +1,15 @@
+/** Kids of keys that sign external (v2) contexts carry this prefix, and only those kids do. */
+export declare const ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX = "external-";
+/**
+ * True when the token names an external key or claims the external version. Unverified: only the
+ * SDK's own refusal and verifier dispatch may use it, never a trust decision, so it stays internal.
+ */
+export declare function isExternalContextToken(token: string | null): boolean;
+/** Verifies the EdDSA signature against the pinned key set and returns the still-untyped payload. */
+export declare function verifySignedContext({ token, publicKeys }: {
+    token: string | null;
+    publicKeys: Readonly<Record<string, string>>;
+}): {
+    kid: string;
+    payload: unknown;
+};

package/dist/server/internal/signed-token.js

@@ -0,0 +1,67 @@
+import { createPublicKey, verify } from 'node:crypto';
+import { z } from 'zod';
+/**
+ * Signature handling shared by every Artifact context verifier. It decides nothing about which
+ * context versions a caller accepts: the public v1 verifier, the external verifier and the
+ * broker's dispatching verifier each apply their own version and kid rules on top of it.
+ *
+ * Lives under `server/internal/`, which the package exports map does not expose.
+ */
+const MAX_CONTEXT_TOKEN_LENGTH = 32768;
+/** Kids of keys that sign external (v2) contexts carry this prefix, and only those kids do. */
+export const ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX = 'external-';
+const headerSchema = z.object({ alg: z.literal('EdDSA'), typ: z.literal('JWT'), kid: z.string().min(1).max(255) }).strict();
+class SignedContextError extends Error {
+    constructor() { super('Invalid signed Artifact context'); this.name = 'SignedContextError'; }
+}
+function decodeSegment(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value))
+        throw new SignedContextError();
+    return JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+}
+function splitToken(token) {
+    if (!token || token.length > MAX_CONTEXT_TOKEN_LENGTH)
+        throw new SignedContextError();
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        throw new SignedContextError();
+    const [header, payload, signature] = parts;
+    return [header, payload, signature];
+}
+/**
+ * Reads the kid and the version claim WITHOUT verifying the signature. Use it only to refuse
+ * early or to choose which verifier runs; never to trust a claim. Null when the token is malformed.
+ */
+function peekSignedContext(token) {
+    try {
+        const [encodedHeader, encodedPayload] = splitToken(token);
+        const header = headerSchema.parse(decodeSegment(encodedHeader));
+        const payload = decodeSegment(encodedPayload);
+        const v = payload !== null && typeof payload === 'object' && 'v' in payload ? payload.v : undefined;
+        return { kid: header.kid, v };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when the token names an external key or claims the external version. Unverified: only the
+ * SDK's own refusal and verifier dispatch may use it, never a trust decision, so it stays internal.
+ */
+export function isExternalContextToken(token) {
+    const peeked = peekSignedContext(token);
+    return peeked !== null && (peeked.kid.startsWith(ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX) || peeked.v === 2);
+}
+/** Verifies the EdDSA signature against the pinned key set and returns the still-untyped payload. */
+export function verifySignedContext({ token, publicKeys }) {
+    const [encodedHeader, encodedPayload, signature] = splitToken(token);
+    const header = headerSchema.parse(decodeSegment(encodedHeader));
+    const pem = Object.hasOwn(publicKeys, header.kid) ? publicKeys[header.kid] : undefined;
+    if (!pem || !/^[A-Za-z0-9_-]+$/.test(signature))
+        throw new SignedContextError();
+    const key = createPublicKey(pem);
+    if (key.asymmetricKeyType !== 'ed25519' ||
+        !verify(null, Buffer.from(`${encodedHeader}.${encodedPayload}`), key, Buffer.from(signature, 'base64url')))
+        throw new SignedContextError();
+    return { kid: header.kid, payload: decodeSegment(encodedPayload) };
+}

package/dist/server/internal/v1-context.d.ts

@@ -0,0 +1,18 @@
+import { type ArtifactRequestContext } from '../request-context.js';
+/**
+ * The v1 rules that apply once a signature has been verified and the caller has applied its own
+ * kid and version rules: schema, then the project, environment, clock and route bindings. Every
+ * failure is an ArtifactContextError. Internal: it trusts `payload`, so it must only ever see a
+ * payload whose signature was just verified.
+ *
+ * Shared by the public v1 verifier and the broker's dispatching verifier, so each applies its own
+ * gate in front of it and pays for one signature check.
+ */
+export declare function parseV1Context({ payload, projectId, environment, method, path, now }: {
+    payload: unknown;
+    projectId: string;
+    environment: string;
+    method?: string;
+    path?: string;
+    now: number;
+}): ArtifactRequestContext;

package/dist/server/internal/v1-context.js

@@ -0,0 +1,26 @@
+import { ArtifactContextError, artifactRequestContextSchema } from '../request-context.js';
+/**
+ * The v1 rules that apply once a signature has been verified and the caller has applied its own
+ * kid and version rules: schema, then the project, environment, clock and route bindings. Every
+ * failure is an ArtifactContextError. Internal: it trusts `payload`, so it must only ever see a
+ * payload whose signature was just verified.
+ *
+ * Shared by the public v1 verifier and the broker's dispatching verifier, so each applies its own
+ * gate in front of it and pays for one signature check.
+ */
+export function parseV1Context({ payload, projectId, environment, method, path, now }) {
+    const parsed = artifactRequestContextSchema.safeParse(payload);
+    if (!parsed.success)
+        throw new ArtifactContextError();
+    const context = parsed.data;
+    if (context.projectId !== projectId || context.environment !== environment ||
+        context.exp <= now || context.iat > now + 5 ||
+        (method !== undefined && context.method !== method.toUpperCase()) || (path !== undefined && context.path !== path))
+        throw new ArtifactContextError();
+    Object.freeze(context.bridge);
+    Object.freeze(context.lattice);
+    Object.freeze(context.capabilities);
+    if (context.taskRoutes)
+        Object.freeze(context.taskRoutes);
+    return Object.freeze(context);
+}

package/dist/server/internal/verify-any.d.ts

@@ -0,0 +1,22 @@
+import { type ArtifactGatewayPublicKeys, type ArtifactRequestContext, type RequestContextV2External } from '../request-context.js';
+export type AnyArtifactRequestContext = ArtifactRequestContext | RequestContextV2External;
+/**
+ * Version-dispatching verifier for platform code that must accept both Atlas-user (v1) and
+ * external (v2) contexts, such as the broker. Applications never get this: it is not exported
+ * from `./server` or `./server/context`, and the exports map does not expose `server/internal`.
+ *
+ * Kid and version are paired both ways: an `external-` kid must sign a v2 context, and a v2
+ * context must be signed by an `external-` kid. This pairing is the only thing standing between
+ * an `external-` kid and the v1 rules: the v1 branch goes straight to the shared v1 parser, not
+ * through the public verifier's own external gate. A v2 context in `development` mode is refused
+ * until development leases can admit it. The signature is checked once per call.
+ */
+export declare function verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, now }: {
+    token: string | null;
+    publicKeys: ArtifactGatewayPublicKeys;
+    projectId: string;
+    environment: string;
+    method?: string;
+    path?: string;
+    now?: number;
+}): AnyArtifactRequestContext;

package/dist/server/internal/verify-any.js

@@ -0,0 +1,61 @@
+import { ArtifactContextError, requestContextV2ExternalSchema, } from '../request-context.js';
+import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX, verifySignedContext } from './signed-token.js';
+import { parseV1Context } from './v1-context.js';
+import { canonicalizeIngressPath, signedIngressPath } from '../ingress-routes.js';
+/**
+ * Version-dispatching verifier for platform code that must accept both Atlas-user (v1) and
+ * external (v2) contexts, such as the broker. Applications never get this: it is not exported
+ * from `./server` or `./server/context`, and the exports map does not expose `server/internal`.
+ *
+ * Kid and version are paired both ways: an `external-` kid must sign a v2 context, and a v2
+ * context must be signed by an `external-` kid. This pairing is the only thing standing between
+ * an `external-` kid and the v1 rules: the v1 branch goes straight to the shared v1 parser, not
+ * through the public verifier's own external gate. A v2 context in `development` mode is refused
+ * until development leases can admit it. The signature is checked once per call.
+ */
+export function verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, now = Math.floor(Date.now() / 1000) }) {
+    let kid;
+    let payload;
+    try {
+        ({ kid, payload } = verifySignedContext({ token, publicKeys }));
+    }
+    catch {
+        throw new ArtifactContextError();
+    }
+    const external = kid.startsWith(ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX);
+    const claimsV2 = payload !== null && typeof payload === 'object' && 'v' in payload && payload.v === 2;
+    if (external !== claimsV2)
+        throw new ArtifactContextError();
+    if (!claimsV2)
+        return parseV1Context({ payload, projectId, environment, method, path, now });
+    const parsed = requestContextV2ExternalSchema.safeParse(payload);
+    if (!parsed.success)
+        throw new ArtifactContextError();
+    const context = parsed.data;
+    if (context.mode !== 'published')
+        throw new ArtifactContextError('external_mode_not_accepted');
+    // The gateway signs only a canonical path (plus its raw query); the caller's path is
+    // canonicalised the same way before comparing, so an encoded or dot-segment variant never binds.
+    if (signedPathOf(context.path) !== context.path)
+        throw new ArtifactContextError();
+    if (context.projectId !== projectId || context.environment !== environment ||
+        context.exp <= now || context.iat > now + 5 ||
+        (method !== undefined && context.method !== method.toUpperCase()) || (path !== undefined && context.path !== signedPathOf(path)))
+        throw new ArtifactContextError();
+    return freezeExternalContext(context);
+}
+function signedPathOf(raw) {
+    const canonical = canonicalizeIngressPath(raw);
+    return canonical && signedIngressPath(canonical);
+}
+function freezeExternalContext(context) {
+    const { principal } = context;
+    Object.freeze(principal.pass);
+    Object.freeze(principal.client);
+    if (principal.amr)
+        Object.freeze(principal.amr);
+    Object.freeze(principal);
+    Object.freeze(context.crit);
+    Object.freeze(context.ext);
+    return Object.freeze(context);
+}

package/dist/server/logger.d.ts

@@ -17,7 +17,7 @@ export interface ArtifactLogRecord extends ArtifactLogMetadata {
 }
 /** Structured events deliberately exclude request bodies, URLs, arbitrary messages and error objects. */
 export declare function createArtifactLogger({ context, sink }: {
-    context: ArtifactRequestContext;
+    context: Pick<ArtifactRequestContext, 'projectId' | 'requestId' | 'deploymentId' | 'devSessionId'>;
     sink?: (record: ArtifactLogRecord) => void;
 }): {
     info: (event: string, metadata?: ArtifactLogMetadata) => void;

package/dist/server/principal.d.ts

@@ -0,0 +1,48 @@
+import { type ArtifactRequestContext, type RequestContextV2External } from './request-context.js';
+/** A caller admitted through a manifest-declared ingress, as the gateway verified it. */
+export interface ArtifactExternalPrincipal {
+    readonly kind: 'external';
+    /** Routing label of the ingress that admitted the caller. Not an authorization attribute. */
+    readonly ingress: string;
+    readonly provider: string;
+    readonly issuer: string;
+    /** The identity provider's raw subject (not `ext|`-namespaced). */
+    readonly subject: string;
+    /** Normalized and verified. */
+    readonly email: string;
+    readonly emailVerified: true;
+    readonly authTime: number | null;
+    readonly amr: readonly string[] | null;
+    readonly tokenIssuedAt: number;
+    readonly client: {
+        readonly ip: string;
+        /** Observed, not proven: the browser chooses it. */
+        readonly userAgent: string;
+        readonly userAgentSha256: string;
+        readonly origin: string | null;
+    };
+}
+/** Who this request acts for. Only `external` callers come through an ingress. */
+export type ArtifactPrincipal = {
+    readonly kind: 'atlas_user';
+    readonly sub: string;
+} | {
+    readonly kind: 'platform_service';
+    readonly sub: string;
+} | ArtifactExternalPrincipal;
+export declare function principalFromContext(context: ArtifactRequestContext | RequestContextV2External): ArtifactPrincipal;
+/** The evidence variables an external caller's verified sign-in supplies. */
+export interface ArtifactExternalEvidence {
+    authSubject: string;
+    actorEmail: string;
+    authTime: number | null;
+    authMethods: readonly string[] | null;
+    ipAddress: string;
+    userAgent: string;
+}
+/**
+ * The sanctioned mapping from a verified external principal to evidence variables. On
+ * manifest-declared evidence operations the broker overwrites (or refuses) these from the same
+ * principal, so a mistake here cannot misattribute evidence there.
+ */
+export declare function externalEvidence(principal: ArtifactPrincipal): ArtifactExternalEvidence;

package/dist/server/principal.js

@@ -0,0 +1,39 @@
+import { ARTIFACT_SERVICE_ACCOUNT_SUB_PREFIX } from './request-context.js';
+export function principalFromContext(context) {
+    if (context.v === 1) {
+        return Object.freeze(context.sub.startsWith(ARTIFACT_SERVICE_ACCOUNT_SUB_PREFIX)
+            ? { kind: 'platform_service', sub: context.sub }
+            : { kind: 'atlas_user', sub: context.sub });
+    }
+    const { principal } = context;
+    return Object.freeze({
+        kind: 'external',
+        ingress: principal.ingress,
+        provider: principal.provider,
+        issuer: principal.issuer,
+        subject: principal.subject,
+        email: principal.email,
+        emailVerified: principal.emailVerified,
+        authTime: principal.authTime,
+        amr: principal.amr,
+        tokenIssuedAt: principal.tokenIssuedAt,
+        client: Object.freeze({ ...principal.client }),
+    });
+}
+/**
+ * The sanctioned mapping from a verified external principal to evidence variables. On
+ * manifest-declared evidence operations the broker overwrites (or refuses) these from the same
+ * principal, so a mistake here cannot misattribute evidence there.
+ */
+export function externalEvidence(principal) {
+    if (principal.kind !== 'external')
+        throw new TypeError('externalEvidence requires an external principal');
+    return {
+        authSubject: principal.subject,
+        actorEmail: principal.email,
+        authTime: principal.authTime,
+        authMethods: principal.amr,
+        ipAddress: principal.client.ip,
+        userAgent: principal.client.userAgent,
+    };
+}

package/dist/server/processes.d.ts

@@ -4,6 +4,11 @@ export interface ArtifactProcessStart {
     process: string;
     /** Idempotency key: starting the same run id again returns the existing run. */
     runId?: string;
+    /**
+     * Enter the graph at this node in place of the process's start node, as `start_node_id` does on
+     * `POST /api/lattice/runs`; Atlas refuses a node the process does not have.
+     */
+    startNodeId?: string;
     title?: string;
     entity?: {
         type: string;
@@ -214,6 +219,51 @@ export interface ArtifactProcessAdvanceResult {
     /** The step had already been completed with this decision; nothing was re-run. */
     idempotent_replay: boolean;
 }
+/** The result of cancelling a run. Cancelling an already-cancelled run replays without a second intervention. */
+export interface ArtifactProcessCancelResult {
+    /** The cancelled run, redacted as `getRun` returns it; null if Atlas could not reload it. */
+    run: ArtifactProcessRunRecord | null;
+    idempotent_replay: boolean;
+}
+/** Resetting a generating agent step: the step settles and the run re-parks at the node's reset edge. */
+export interface ArtifactProcessResetStep {
+    runId: string;
+    stepId: string;
+}
+export interface ArtifactProcessResetStepResult {
+    run_id: string;
+    step_id: string;
+    node_id: string;
+    reset_edge_id: string;
+    resume_node_id: string;
+    /** The resume node was dispatched again. */
+    redispatched: boolean;
+    /** The run's status after the reset. */
+    status: ArtifactProcessRunStatus | null;
+}
+/** A page of a run's events after a cursor. */
+export interface ArtifactProcessRunEventsQuery {
+    runId: string;
+    /** The `event_cursor` from `getRun`, or the `cursor` the previous page returned. Omitted reads from the run's first event. */
+    since?: string;
+    /** At most ARTIFACT_PROCESS_RUN_EVENTS_LIMIT; Lattice defaults to 500. */
+    limit?: number;
+}
+/** One event on a run, as the run's stream sends it. Payloads are redacted when the event is written. */
+export interface ArtifactProcessRunEvent {
+    id: string;
+    run_id: string;
+    node_id: string | null;
+    event_type: string;
+    source: string;
+    payload: unknown;
+    created_at: string;
+}
+export interface ArtifactProcessRunEvents {
+    events: ArtifactProcessRunEvent[];
+    /** Pass as `since` on the next poll. Null only when the run has no events yet and no `since` was given. */
+    cursor: string | null;
+}
 /** Users (Auth0 `sub`) and chat groups (group id) to name in an assignment or a share. */
 export interface ArtifactProcessPrincipals {
     users?: string[];
@@ -274,6 +324,12 @@ export interface ArtifactServerProcesses {
     advance(input: ArtifactProcessAdvance): Promise<ArtifactProcessAdvanceResult>;
     /** Reassign a parked human step; the user's `owner` relation on the run decides. */
     assign(input: ArtifactProcessAssign): Promise<ArtifactProcessAssignResult>;
+    /** Cancel a run of a process declared under `processes.act`; the user's `invoker` relation on the run decides. */
+    cancel(runId: string): Promise<ArtifactProcessCancelResult>;
+    /** Reset a generating agent step without cancelling its run; the user's `invoker` relation on the run decides. */
+    resetStep(input: ArtifactProcessResetStep): Promise<ArtifactProcessResetStepResult>;
+    /** A page of a run's events after a cursor, oldest first; poll with the returned cursor to see each event once. */
+    listEvents(query: ArtifactProcessRunEventsQuery): Promise<ArtifactProcessRunEvents>;
     /** The explicit viewer grants on a run of a process declared under `processes.act`; owner-gated. */
     listViewers(runId: string): Promise<ArtifactProcessRunViewers>;
     /** Share a run with users and groups; owner-gated, additive, idempotent. */

package/dist/server/processes.js

@@ -36,6 +36,19 @@ export function createArtifactProcessesClient({ mode, json }) {
         assign: async (input) => {
             return await json(artifactServerRequestSchema.parse({ operation: 'lattice_assign', mode, ...input }));
         },
+        cancel: async (runId) => {
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_cancel', mode, runId }));
+        },
+        resetStep: async (input) => {
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_reset_step', mode, ...input }));
+        },
+        listEvents: async (query) => {
+            const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_run_events', mode, ...query }));
+            if (!Array.isArray(body?.events) || !(typeof body.cursor === 'string' || body.cursor === null)) {
+                throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed event page');
+            }
+            return body;
+        },
         listViewers: async (runId) => {
             return await json(artifactServerRequestSchema.parse({ operation: 'lattice_viewers', mode, runId }));
         },