@godxjp/sdk 0.5.0 → 0.7.0

package/README.md

@@ -13,6 +13,7 @@ Entries are split by **who owns the contract**, not by what happens to be duplic
 | `.`          | Platform contracts: permission DTO, tenant-scoped channel names    | Binds every product at once |
 | `./laravel`  | House conventions for Laravel + React: HTTP client, `ApiError`     | Moves faster                |
 | `./realtime` | Realtime seam: configuration, connection status, channel listeners | Moves faster                |
+| `./agent`    | Server side: who is calling (person, workload, AI agent), effect keys | Binds every product at once |
 
 ## Scope — what belongs here, and what does not
 
@@ -155,6 +156,117 @@ An unreachable server (`status: 0`) keeps its built-in text, `Could not reach th
 
 **Changed in 0.4.0.** Additions only; a client configured for 0.3.0 sends and throws exactly what it did. `ApiError` gains `body` (also on a `download()` failure). `onUnauthorized` now receives the request that was answered 401 (`{ method, url, headers }`); a function that takes no argument still works. `networkErrors: "throw"` rethrows `fetch`'s own error instead of `ApiError(0)` — including a response body that breaks off mid-way.
 
+### Replacing a hand-written `session-expiry.ts`
+
+A product that wrapped `fetch` to send the browser to sign in on an expired session does not need that file: the client already does it.
+
+```ts
+export const apiClient = createClient({
+  baseUrl: "/api/app/v1",
+  signInUrl: (returnTo) => `/login?return=${encodeURIComponent(returnTo)}`,
+});
+```
+
+What happens on a **401**, in order:
+
+1. If `onUnauthorized` is given, it is called with the request that was answered 401. Resolve `true` (a token was refreshed) and the request is sent once more — never more than once; resolve `false` and the 401 goes on to step 2. 401s that arrive together share one call.
+2. If `signInUrl` is given, the browser goes to `signInUrl(pathname + search)` with `window.location.assign` — once, however many requests were answered 401 at the same moment. If the user comes Back and the page is restored from the back/forward cache (`pageshow` with `persisted`), the next 401 sends them again.
+3. The call still rejects with `ApiError(401)`, so a screen that was waiting does not hang.
+
+A **419** (CSRF token expired) is **not** redirected: it rejects with `ApiError(419)` and nothing else. With php-sdk's `SignInErrors::handle`, the JSON body is `{ error: "session_expired", message, request_id }`, so read `error.body` when a screen should react:
+
+```ts
+if (error instanceof ApiError && error.status === 419) {
+  window.location.reload(); // or show the message from error.body
+}
+```
+
+## `./errors` — the shared sign-in error page
+
+**New in 0.6.0.** Every GoDX service shows the same page, with the same words, for a failed sign-in or a refused access: not a member of the organization, no entitlement, inactive subscription, locked or unverified account, a broken SSO callback, the platform not answering, an expired session, a 403 inside the app.
+
+php-sdk owns the codes, the ja/vi/en sentences and the redirect to the error route; this entry only types the payload and renders it. The page has **no copy of its own** — title, description, the IdP's detail and every action label arrive translated in the payload.
+
+```tsx
+// resources/js/pages/GodxSignInError.tsx — the whole file
+export { SignInErrorPage as default } from "@godxjp/sdk/errors";
+```
+
+The `error` prop (php-sdk's `SignInErrorPresenter`):
+
+```ts
+type SignInErrorPayload = {
+  code: SignInErrorCode;     // see SIGN_IN_ERROR_CODES
+  status: number;            // 401, 403, 419, 429, 503 …
+  title: string;
+  description: string;
+  detail: string | null;     // the IdP's error_description — from the session, never the URL
+  request_id: string | null;
+  action: { kind: "retry" | "switch_organization" | "home"; href: string; label: string } | null;
+};
+```
+
+- `action` is the page's one call to action, a link to `href` labelled `label`; `null` renders no button.
+- `request_id` is shown as a labelled support id; `detail`, when present, follows the description.
+- `status` is shown as sent. The page is built only from public `@godxjp/ui` components (`ErrorSurface` in `system` mode and `Button`); ErrorSurface draws a status it has no curated glyph for (401, 419, 429) with its 4xx fallback.
+- `SIGN_IN_ERROR_CODES` lists every code; codes are only ever added.
+
+## `./agent` — AI agents as callers
+
+Server-side and framework-free: no DOM, no React. For a service that receives GoDX access tokens (godx-jp/id#2066, #2074, #2075).
+
+An AI agent's token says `prn: "agent"` and `sub` = the **agent** — never a person. The person who asked and the person who answers for the agent come in `act: { sub: <requester>, act: { sub: <sponsor> } }`; a write also carries its one `gx_execution_id` and `gx_effect_key`.
+
+```ts
+import {
+  principalFromIntrospection,
+  principalFromClaims,
+  admitPrincipal,
+  actorId,
+  responsibleUserId,
+  PrincipalError,
+} from "@godxjp/sdk/agent";
+
+// From Platform's RFC 7662 answer — or principalFromClaims(claims) for claims your server already verified.
+const principal = principalFromIntrospection(answer, {
+  issuer: "https://id.godx.jp",
+  resource: "https://task.godx.jp/mcp", // an agent's token carries the publication's resource URI
+  allowAgents: true, // this route's explicit opt-in; off by default
+});
+
+audit.record({ actor: actorId(principal), responsible: responsibleUserId(principal) });
+```
+
+- A `prn` other than `user`, `workload` or `agent` is refused (`PrincipalError`, `status: 401`). An agent on a route without `allowAgents: true` is refused with `status: 403`, `code: "agent_not_admitted"`; `admitPrincipal(principal, { allowAgents })` is the same guard for a principal you already hold.
+- An agent is refused unless `act` is exactly `{requester, {sponsor}}`, `requester_user_id` repeats `act.sub`, the profile is `gx_agent_service_v1`, it is DPoP-bound, and an effect key comes with its execution. From introspection, `service_authorization` must also name the same agent, requester, sponsor and run.
+- `actorId()` is who did it (the agent); `responsibleUserId()` is who answers for it — the requester for an agent, the user for a user, `null` for a workload. Never read `subject` as a person without `isAgent()`.
+- Authorization stays the service's own live check of the agent's permissions, exactly as for a person.
+
+### Applying a write once per effect key
+
+Platform cannot see the service's database, so only the service can make "the same effect twice" impossible: commit a row keyed on the effect key in the same transaction as the write. Back `EffectLedger` with one table whose primary key is the effect key, and `insertIfAbsent` with `INSERT … ON CONFLICT DO NOTHING`:
+
+```ts
+import { applyEffect, createExecutionClient, EffectRefused } from "@godxjp/sdk/agent";
+
+const executions = createExecutionClient({ issuer: "https://id.godx.jp", clientId, clientSecret });
+
+const effect = await applyEffect({
+  ledger, // your EffectLedger: find / transaction(insertIfAbsent, saveResult) / markReported
+  executions,
+  principal,
+  accessToken, // sent to Platform's checkpoint only — never forward it to another service
+  tool: "issue_create",
+  arguments: input,
+  write: async (tx) => ({ issue_id: await tx.insertIssue(input) }), // every write of the effect, on tx
+});
+// effect.replayed: already applied under this key; the write did not run again.
+```
+
+`applyEffect` answers a replay from the ledger first (retrying an unsent report), then asks Platform's execution checkpoint as the service and requires it to name this execution and key, runs the write once with the ledger row (`runOnce`), and reports the outcome — `failed` when the write throws, which is then rethrown. `EffectRefused` means nothing was written.
+
+The PHP SDK (`godx-jp/php-sdk`) carries the same contract, a table-backed ledger and the "agent-ready" contract test kit a service runs before Platform grants agents its tools.
+
 ## `./realtime`
 
 ```ts
@@ -223,6 +335,8 @@ Build with `organizationChannel` / `platformChannel`, parse with `parseChannelNa
 
 `./realtime` needs `@laravel/echo-react` and `react`. Both are optional peers: an application using only `./laravel` installs neither.
 
+`./errors` needs `@godxjp/ui` (19.2.0 or later — the first release whose `ErrorSurface` takes any status — below 34) and `react`, both optional peers too. It imports no stylesheet: the application already loads `@godxjp/ui/styles`, and the page should sit inside its `AppProvider` so the kit's own labels (such as "Request ID") follow the locale.
+
 ## Licence
 
 Apache-2.0.

package/dist/agent/index.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Who is calling a GoDX service — a person, a workload, or an AI agent acting for a person
+ * (godx-jp/id#2066, #2074, #2075).
+ *
+ * An agent's token says `prn: "agent"` and `sub` = the AGENT, never a person. The person at the
+ * head of the chain and the person who answers for the agent come in `act`:
+ *
+ *   act = { sub: <requester>, act: { sub: <sponsor> } }
+ *
+ * Read a principal only through {@link principalFromClaims} (claims your server already verified)
+ * or {@link principalFromIntrospection} (Platform's RFC 7662 answer). Both refuse a `prn` they do
+ * not know, and refuse an agent unless the caller opts in with `allowAgents: true`.
+ */
+type PrincipalKind = "user" | "workload" | "agent";
+interface Principal {
+    readonly kind: PrincipalKind;
+    /** The token's `sub`: the user, the workload — or, for an agent, the AGENT. */
+    readonly subject: string;
+    /** The organization context the token is scoped to (`organization_context_id`, else `organization_id`). */
+    readonly organization: string;
+    /** Platform's organization id (`organization_id`), when the token carries one. */
+    readonly organizationId: string | null;
+    readonly clientId: string;
+    readonly tokenId: string;
+    readonly scopes: readonly string[];
+    /** Agent only: the person who asked for the work (`act.sub`). */
+    readonly requesterUserId: string | null;
+    /** Agent only: the person who answers for the agent in this organization (`act.act.sub`). */
+    readonly sponsorUserId: string | null;
+    /** Agent only: the run the call belongs to. */
+    readonly agentRunId: string | null;
+    /** A write binding's ONE execution (`gx_execution_id`). */
+    readonly executionId: string | null;
+    /** Agent write only: the key the service must deduplicate the write on (`gx_effect_key`). */
+    readonly effectKey: string | null;
+}
+type PrincipalErrorCode = "inactive" | "unknown_principal" | "agent_not_admitted" | "malformed_token" | "malformed_agent" | "context_mismatch";
+declare class PrincipalError extends Error {
+    readonly code: PrincipalErrorCode;
+    /** 403 for an agent on a route that did not opt in; 401 for everything else. */
+    readonly status: 401 | 403;
+    constructor(code: PrincipalErrorCode, message: string);
+}
+interface PrincipalOptions {
+    /** The route's explicit opt-in for AI agents. Off by default. */
+    allowAgents?: boolean;
+}
+interface IntrospectionOptions extends PrincipalOptions {
+    /** Platform's issuer, exactly as it signs `iss`. */
+    issuer: string;
+    /** This resource's audience — for an agent, the publication's resource URI. */
+    resource: string;
+}
+/** The only token profile an agent's `prn: "agent"` may arrive under. */
+declare const AGENT_ACCESS_POLICY = "gx_agent_service_v1";
+declare function isAgent(principal: Principal): boolean;
+/** Who performed the call: the agent, the user or the workload. Record it as the actor. */
+declare function actorId(principal: Principal): string;
+/** Who answers for the call: the requester for an agent, the user for a user, nobody for a workload. */
+declare function responsibleUserId(principal: Principal): string | null;
+/**
+ * The guard a route puts in front of its handler: refuses an agent unless the route opted in.
+ * Unknown lanes never get this far — the parsers refuse them.
+ */
+declare function admitPrincipal(principal: Principal, options?: PrincipalOptions): Principal;
+/**
+ * A principal from access-token claims the server has ALREADY verified (signature, issuer,
+ * audience, lifetime, DPoP). This function checks the lane and the agent chain, not the signature.
+ */
+declare function principalFromClaims(claims: unknown, options?: PrincipalOptions): Principal;
+/**
+ * A principal from Platform's introspection answer (RFC 7662). Beyond {@link principalFromClaims}
+ * it requires the token active, issued by `issuer` for `resource`, and — for an agent — that
+ * `service_authorization` describes the SAME caller Platform resolves now: `principal: "agent"`,
+ * the agent, requester, sponsor, run, execution and effect key.
+ */
+declare function principalFromIntrospection(response: unknown, options: IntrospectionOptions): Principal;
+
+/**
+ * The resource instance's side of a mutation binding call (godx-jp/id#1447, #2074).
+ *
+ * Both calls authenticate with the SERVICE's own confidential client, never with the caller's
+ * token: `checkpoint` is asked before every write, `outcome` once at the end. The caller's token
+ * travels in the checkpoint BODY, to the issuer that minted it — the only place it may ever go.
+ */
+declare const CHECKPOINT_PATH = "api/gx/v1/executions/checkpoints";
+declare const OUTCOME_PATH = "api/gx/v1/executions/outcome";
+interface ExecutionClientConfig {
+    /** Platform's issuer, e.g. `https://id.godx.jp`. */
+    issuer: string;
+    /** This service instance's client credential. */
+    clientId: string;
+    clientSecret: string;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+interface CheckpointRequest {
+    accessToken: string;
+    /** What kind of effect is about to happen, e.g. `write`. */
+    effect: string;
+    tool: string;
+    /** The tool input exactly as the person approved it; Platform compares its digest. */
+    arguments: Record<string, unknown>;
+}
+interface CheckpointDecision {
+    allowed: boolean;
+    /** `allowed`, Platform's refusal reason (`already_applied`, `mismatch`, `not_running`, …), or `unavailable` / `invalid_response`. */
+    reason: string;
+    executionId: string | null;
+    sequence: number | null;
+    effectKey: string | null;
+    /** On `already_applied`: the outcome the service reported the first time. */
+    outcome: Record<string, unknown> | null;
+}
+interface OutcomeReport {
+    executionId: string;
+    succeeded: boolean;
+    /** At most 16 KiB of JSON; Platform returns it on a replayed checkpoint. */
+    outcome?: Record<string, unknown>;
+}
+interface ExecutionClient {
+    /** Fails closed: a refusal, an outage or a malformed answer is `allowed: false`. */
+    checkpoint(request: CheckpointRequest): Promise<CheckpointDecision>;
+    /** Resolves `true` once Platform recorded it — also when it was already recorded (409). */
+    outcome(report: OutcomeReport): Promise<boolean>;
+}
+declare function createExecutionClient(config: ExecutionClientConfig): ExecutionClient;
+
+/**
+ * Apply an AI agent's write AT MOST ONCE per effect key (godx-jp/id#2074, #2075).
+ *
+ * Platform mints one `effect_key` per approved write and cannot see the service's database, so
+ * only the service can make "the same effect twice" impossible — by committing a row keyed on the
+ * effect key IN THE SAME TRANSACTION as the write. This module owns the protocol; the service
+ * backs {@link EffectLedger} with its own database (one table with the effect key as primary key).
+ */
+
+interface EffectRecord {
+    effectKey: string;
+    executionId: string;
+    agentId: string;
+    requesterUserId: string;
+    organization: string;
+    /** What the first run returned; replayed as-is. */
+    result: Record<string, unknown> | null;
+    /** Whether Platform has the outcome; a replay retries the report when it does not. */
+    reported: boolean;
+}
+/** What the service's transaction offers the ledger. Everything runs on the service's own connection. */
+interface EffectLedgerTransaction {
+    /**
+     * Insert `record` unless its effect key exists (`INSERT … ON CONFLICT DO NOTHING`). Resolve null
+     * when THIS call inserted it, the existing record otherwise. A concurrent insert of the same key
+     * must wait for the other transaction — a primary key gives exactly that.
+     */
+    insertIfAbsent(record: EffectRecord): Promise<EffectRecord | null>;
+    saveResult(effectKey: string, result: Record<string, unknown> | null): Promise<void>;
+}
+/** `Tx` is the service's own transaction handle, extended with the two ledger operations. */
+interface EffectLedger<Tx extends EffectLedgerTransaction = EffectLedgerTransaction> {
+    find(effectKey: string): Promise<EffectRecord | null>;
+    /** Run `work` in ONE transaction of the service's database; a throw rolls everything back. */
+    transaction<R>(work: (tx: Tx) => Promise<R>): Promise<R>;
+    markReported(effectKey: string): Promise<void>;
+}
+interface EffectResult {
+    /** True when the key was already applied and the write did not run again. */
+    replayed: boolean;
+    result: Record<string, unknown> | null;
+    reported: boolean;
+}
+declare class EffectRefused extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+type EffectWrite<T> = (tx: T) => Promise<Record<string, unknown> | null>;
+/**
+ * The deduplication alone: run `write` once per effect key, inside the ledger's transaction.
+ * `write` receives the transaction so every database write of the effect commits with the row.
+ */
+declare function runOnce<Tx extends EffectLedgerTransaction>(ledger: EffectLedger<Tx>, principal: Principal, write: EffectWrite<Tx>): Promise<EffectResult>;
+interface ApplyEffectRequest<Tx extends EffectLedgerTransaction> {
+    ledger: EffectLedger<Tx>;
+    executions: ExecutionClient;
+    principal: Principal;
+    /** The incoming token — sent to Platform's checkpoint only, never anywhere else. */
+    accessToken: string;
+    tool: string;
+    arguments: Record<string, unknown>;
+    write: EffectWrite<Tx>;
+    effect?: string;
+}
+/**
+ * The whole lane: a replay is answered from the ledger (and its unsent report retried); otherwise
+ * Platform's checkpoint must allow THIS execution and key, the write runs once, and the outcome is
+ * reported `succeeded` — or `failed` when the write throws, which is then rethrown.
+ */
+declare function applyEffect<Tx extends EffectLedgerTransaction>(request: ApplyEffectRequest<Tx>): Promise<EffectResult>;
+
+export { AGENT_ACCESS_POLICY, type ApplyEffectRequest, CHECKPOINT_PATH, type CheckpointDecision, type CheckpointRequest, type EffectLedger, type EffectLedgerTransaction, type EffectRecord, EffectRefused, type EffectResult, type EffectWrite, type ExecutionClient, type ExecutionClientConfig, type IntrospectionOptions, OUTCOME_PATH, type OutcomeReport, type Principal, PrincipalError, type PrincipalErrorCode, type PrincipalKind, type PrincipalOptions, actorId, admitPrincipal, applyEffect, createExecutionClient, isAgent, principalFromClaims, principalFromIntrospection, responsibleUserId, runOnce };

package/dist/agent/index.js

@@ -0,0 +1,362 @@
+// src/agent/principal.ts
+var PrincipalError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "PrincipalError";
+    this.status = code === "agent_not_admitted" ? 403 : 401;
+  }
+  code;
+  /** 403 for an agent on a route that did not opt in; 401 for everything else. */
+  status;
+};
+var AGENT_ACCESS_POLICY = "gx_agent_service_v1";
+var KINDS = ["user", "workload", "agent"];
+var AGENT_ONLY_CLAIMS = ["requester_user_id", "agent_run_id", "gx_effect_key"];
+function isAgent(principal) {
+  return principal.kind === "agent";
+}
+function actorId(principal) {
+  return principal.subject;
+}
+function responsibleUserId(principal) {
+  switch (principal.kind) {
+    case "agent":
+      return principal.requesterUserId;
+    case "user":
+      return principal.subject;
+    case "workload":
+      return null;
+  }
+}
+function admitPrincipal(principal, options = {}) {
+  if (principal.kind === "agent" && options.allowAgents !== true) {
+    throw new PrincipalError("agent_not_admitted", "This route does not admit agent principals.");
+  }
+  return principal;
+}
+function principalFromClaims(claims, options = {}) {
+  const record = asRecord(claims);
+  if (record === null) {
+    throw new PrincipalError("malformed_token", "Token claims must be an object.");
+  }
+  const kind = laneOf(record["prn"]);
+  const subject = requiredString(record, "sub");
+  const organization = optionalString(record, "organization_context_id") ?? optionalString(record, "organization_id");
+  if (organization === null) {
+    throw new PrincipalError("malformed_token", "The token names no organization.");
+  }
+  const scope = record["scope"] ?? "";
+  if (typeof scope !== "string") {
+    throw new PrincipalError("malformed_token", "Malformed token scopes.");
+  }
+  const base = {
+    kind,
+    subject,
+    organization,
+    organizationId: optionalString(record, "organization_id"),
+    clientId: requiredString(record, "client_id"),
+    tokenId: requiredString(record, "jti"),
+    scopes: scope.split(" ").filter((value) => value !== ""),
+    executionId: optionalString(record, "gx_execution_id")
+  };
+  if (kind !== "agent") {
+    for (const claim of AGENT_ONLY_CLAIMS) {
+      if (record[claim] !== void 0 && record[claim] !== null) {
+        throw new PrincipalError("malformed_token", "Agent claims on a token that is not an agent's.");
+      }
+    }
+    return Object.freeze({ ...base, requesterUserId: null, sponsorUserId: null, agentRunId: null, effectKey: null });
+  }
+  if (options.allowAgents !== true) {
+    throw new PrincipalError("agent_not_admitted", "This route does not admit agent principals.");
+  }
+  const [requester, sponsor] = agentChain(record);
+  const effectKey = optionalString(record, "gx_effect_key");
+  if (record["access_policy"] !== AGENT_ACCESS_POLICY || base.organizationId === null) {
+    throw new PrincipalError("malformed_agent", "Malformed agent token.");
+  }
+  if (requester === subject) {
+    throw new PrincipalError("malformed_agent", "An agent is never its own requester.");
+  }
+  if (base.executionId === null !== (effectKey === null)) {
+    throw new PrincipalError("malformed_agent", "An agent write names both its execution and its effect key.");
+  }
+  if (asRecord(record["cnf"]) === null) {
+    throw new PrincipalError("malformed_agent", "An agent token must be DPoP-bound.");
+  }
+  return Object.freeze({
+    ...base,
+    requesterUserId: requester,
+    sponsorUserId: sponsor,
+    agentRunId: requiredString(record, "agent_run_id"),
+    effectKey
+  });
+}
+function principalFromIntrospection(response, options) {
+  const record = asRecord(response);
+  if (record === null || record["active"] !== true) {
+    throw new PrincipalError("inactive", "The token is not active.");
+  }
+  if (record["iss"] !== options.issuer) {
+    throw new PrincipalError("context_mismatch", "Token issuer mismatch.");
+  }
+  const audiences = Array.isArray(record["aud"]) ? record["aud"] : [record["aud"]];
+  if (!audiences.includes(options.resource)) {
+    throw new PrincipalError("context_mismatch", "Token audience mismatch.");
+  }
+  const authorization = asRecord(record["service_authorization"]);
+  const agentAuthority = record["prn"] === "agent" && authorization?.["principal"] === "agent";
+  const principal = principalFromClaims(
+    {
+      ...record,
+      access_policy: agentAuthority ? AGENT_ACCESS_POLICY : record["access_policy"],
+      gx_execution_id: authorization?.["execution_id"] ?? record["gx_execution_id"],
+      gx_effect_key: authorization?.["effect_key"] ?? record["gx_effect_key"]
+    },
+    options
+  );
+  if (principal.kind !== "agent") {
+    if (authorization !== null && (authorization["principal"] ?? "user") !== "user") {
+      throw new PrincipalError("context_mismatch", "The authority describes another caller.");
+    }
+    return principal;
+  }
+  if (authorization === null || authorization["agent_id"] !== principal.subject || authorization["requester_user_id"] !== principal.requesterUserId || authorization["sponsor_user_id"] !== principal.sponsorUserId || authorization["agent_run_id"] !== principal.agentRunId) {
+    throw new PrincipalError("context_mismatch", "The authority describes another caller.");
+  }
+  return principal;
+}
+function laneOf(value) {
+  if (typeof value === "string" && KINDS.includes(value)) {
+    return value;
+  }
+  throw new PrincipalError("unknown_principal", "This credential lane cannot access a consumer resource.");
+}
+function agentChain(record) {
+  const act = asRecord(record["act"]);
+  const sponsor = act === null ? null : asRecord(act["act"]);
+  const requester = act?.["sub"];
+  if (act === null || sponsor === null || "act" in sponsor || typeof requester !== "string" || requester === "" || typeof sponsor["sub"] !== "string" || sponsor["sub"] === "" || record["requester_user_id"] !== requester || typeof record["agent_run_id"] !== "string" || record["agent_run_id"] === "") {
+    throw new PrincipalError("malformed_agent", "Malformed agent actor chain.");
+  }
+  return [requester, sponsor["sub"]];
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function requiredString(record, name) {
+  const value = record[name];
+  if (typeof value !== "string" || value === "") {
+    throw new PrincipalError("malformed_token", `Missing token claim: ${name}.`);
+  }
+  return value;
+}
+function optionalString(record, name) {
+  const value = record[name];
+  if (value === void 0 || value === null) {
+    return null;
+  }
+  if (typeof value !== "string" || value === "") {
+    throw new PrincipalError("malformed_token", `Malformed token claim: ${name}.`);
+  }
+  return value;
+}
+
+// src/agent/execution-client.ts
+var CHECKPOINT_PATH = "api/gx/v1/executions/checkpoints";
+var OUTCOME_PATH = "api/gx/v1/executions/outcome";
+function createExecutionClient(config) {
+  const send = config.fetch ?? fetch;
+  const base = config.issuer.replace(/\/+$/, "") + "/";
+  if (!base.startsWith("https://")) {
+    throw new Error("The execution client needs an https issuer.");
+  }
+  const post = (path, body) => send(base + path, {
+    method: "POST",
+    headers: { Accept: "application/json", "Content-Type": "application/json" },
+    body: JSON.stringify({ client_id: config.clientId, client_secret: config.clientSecret, ...body }),
+    redirect: "error"
+  });
+  return {
+    async checkpoint(request) {
+      const refused = (reason, outcome = null) => ({
+        allowed: false,
+        reason,
+        executionId: null,
+        sequence: null,
+        effectKey: null,
+        outcome
+      });
+      if (request.accessToken === "" || request.effect === "" || request.tool === "") {
+        return refused("invalid_request");
+      }
+      let response;
+      try {
+        response = await post(CHECKPOINT_PATH, {
+          token: request.accessToken,
+          effect: request.effect,
+          tool: request.tool,
+          arguments: request.arguments
+        });
+      } catch {
+        return refused("unavailable");
+      }
+      if (response.status === 429 || response.status >= 500) {
+        return refused("unavailable");
+      }
+      const data = await readJson(response);
+      if (response.status === 403) {
+        const reason = data?.["reason"];
+        const outcome = data?.["outcome"];
+        return refused(typeof reason === "string" && reason !== "" ? reason : "forbidden", isRecord(outcome) ? outcome : null);
+      }
+      const executionId = data?.["execution_id"];
+      const sequence = data?.["sequence"] ?? null;
+      const effectKey = data?.["effect_key"] ?? null;
+      if (response.status !== 200 || data?.["allowed"] !== true || typeof executionId !== "string" || executionId === "" || sequence !== null && !Number.isInteger(sequence) || effectKey !== null && (typeof effectKey !== "string" || effectKey === "")) {
+        return refused(response.ok ? "invalid_response" : "forbidden");
+      }
+      return {
+        allowed: true,
+        reason: "allowed",
+        executionId,
+        sequence,
+        effectKey,
+        outcome: null
+      };
+    },
+    async outcome(report) {
+      try {
+        const response = await post(OUTCOME_PATH, {
+          execution_id: report.executionId,
+          result: report.succeeded ? "succeeded" : "failed",
+          outcome: report.outcome ?? {}
+        });
+        return response.ok || response.status === 409;
+      } catch {
+        return false;
+      }
+    }
+  };
+}
+async function readJson(response) {
+  try {
+    const data = await response.json();
+    return isRecord(data) ? data : null;
+  } catch {
+    return null;
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/agent/effects.ts
+var EffectRefused = class extends Error {
+  constructor(reason) {
+    super(`Agent effect refused: ${reason}.`);
+    this.reason = reason;
+    this.name = "EffectRefused";
+  }
+  reason;
+};
+async function runOnce(ledger, principal, write) {
+  const key = effectKeyOf(principal);
+  return ledger.transaction(async (tx) => {
+    const existing = await tx.insertIfAbsent({
+      effectKey: key,
+      executionId: principal.executionId,
+      agentId: principal.subject,
+      requesterUserId: principal.requesterUserId,
+      organization: principal.organization,
+      result: null,
+      reported: false
+    });
+    if (existing !== null) {
+      assertSameCaller(principal, existing);
+      return { replayed: true, result: existing.result, reported: existing.reported };
+    }
+    const result = await write(tx);
+    if (result !== null && (typeof result !== "object" || Array.isArray(result))) {
+      throw new EffectRefused("write_result_not_an_object");
+    }
+    await tx.saveResult(key, result);
+    return { replayed: false, result, reported: false };
+  });
+}
+async function applyEffect(request) {
+  const { ledger, executions, principal } = request;
+  const key = effectKeyOf(principal);
+  const executionId = principal.executionId;
+  const recorded = await ledger.find(key);
+  if (recorded !== null) {
+    assertSameCaller(principal, recorded);
+    return replay(request, recorded);
+  }
+  const decision = await executions.checkpoint({
+    accessToken: request.accessToken,
+    effect: request.effect ?? "write",
+    tool: request.tool,
+    arguments: request.arguments
+  });
+  if (!decision.allowed) {
+    throw new EffectRefused(decision.reason);
+  }
+  if (decision.executionId !== executionId || decision.effectKey !== key) {
+    throw new EffectRefused("execution_mismatch");
+  }
+  let applied;
+  try {
+    applied = await runOnce(ledger, principal, request.write);
+  } catch (error) {
+    if (!(error instanceof EffectRefused)) {
+      await executions.outcome({ executionId, succeeded: false, outcome: { error: "write_failed" } });
+    }
+    throw error;
+  }
+  if (applied.replayed) {
+    return replay(request, { ...recordOf(principal), result: applied.result, reported: applied.reported });
+  }
+  const reported = await executions.outcome({ executionId, succeeded: true, outcome: applied.result ?? {} });
+  if (reported) {
+    await ledger.markReported(key);
+  }
+  return { replayed: false, result: applied.result, reported };
+}
+async function replay(request, recorded) {
+  let reported = recorded.reported;
+  if (!reported) {
+    reported = await request.executions.outcome({
+      executionId: recorded.executionId,
+      succeeded: true,
+      outcome: recorded.result ?? {}
+    });
+    if (reported) {
+      await request.ledger.markReported(recorded.effectKey);
+    }
+  }
+  return { replayed: true, result: recorded.result, reported };
+}
+function effectKeyOf(principal) {
+  if (principal.kind !== "agent" || principal.effectKey === null || principal.executionId === null) {
+    throw new EffectRefused("no_effect_key");
+  }
+  return principal.effectKey;
+}
+function assertSameCaller(principal, record) {
+  if (record.agentId !== principal.subject || record.executionId !== principal.executionId || record.organization !== principal.organization) {
+    throw new EffectRefused("effect_key_conflict");
+  }
+}
+function recordOf(principal) {
+  return {
+    effectKey: principal.effectKey,
+    executionId: principal.executionId,
+    agentId: principal.subject,
+    requesterUserId: principal.requesterUserId,
+    organization: principal.organization
+  };
+}
+
+export { AGENT_ACCESS_POLICY, CHECKPOINT_PATH, EffectRefused, OUTCOME_PATH, PrincipalError, actorId, admitPrincipal, applyEffect, createExecutionClient, isAgent, principalFromClaims, principalFromIntrospection, responsibleUserId, runOnce };

package/dist/errors/index.d.ts

@@ -0,0 +1,50 @@
+import * as react from 'react';
+
+/**
+ * The shared sign-in / access error vocabulary. php-sdk (`SignInErrorCode`) is the source of truth;
+ * this mirrors it so a page that renders the payload is typed against the same codes.
+ *
+ * Codes are only ever ADDED, never renamed or given a new meaning.
+ */
+declare const SIGN_IN_ERROR_CODES: readonly ["organization_membership_missing", "organization_unavailable", "organization_context_missing", "service_entitlement_missing", "subscription_inactive", "personal_workspace_not_enabled", "user_inactive", "user_unverified", "service_unavailable", "employee_onboarding", "access_denied", "callback_invalid", "token_exchange_failed", "platform_unavailable", "session_expired", "forbidden", "too_many_attempts"];
+type SignInErrorCode = (typeof SIGN_IN_ERROR_CODES)[number];
+type SignInErrorActionKind = "retry" | "switch_organization" | "home";
+/**
+ * The one way out of the error page. `label` is already translated by php-sdk for the request's
+ * locale — the page has no copy of its own, not even for the action button.
+ */
+type SignInErrorAction = {
+    kind: SignInErrorActionKind;
+    href: string;
+    label: string;
+};
+/**
+ * What php-sdk's `SignInErrorPresenter` hands the page (the `error` prop). Every sentence is
+ * already translated.
+ */
+type SignInErrorPayload = {
+    code: SignInErrorCode;
+    status: number;
+    title: string;
+    description: string;
+    /** The IdP's own `error_description`. Only ever carried through the session, never the URL. */
+    detail: string | null;
+    request_id: string | null;
+    /** `null` renders no button. */
+    action: SignInErrorAction | null;
+};
+
+type SignInErrorPageProps = {
+    error: SignInErrorPayload;
+};
+/**
+ * The page every GoDX service shows for a failed sign-in or a refused access. It owns no copy:
+ * title, description, detail and the action label arrive translated in `error`.
+ *
+ * Always `mode="system"` — the page is reached from a sign-in callback or a redirect, where there
+ * is no application shell to keep. `status` is passed through as sent; ErrorSurface draws any
+ * status it has no curated glyph for (401, 419, 429) with its 4xx fallback.
+ */
+declare function SignInErrorPage({ error }: SignInErrorPageProps): react.JSX.Element;
+
+export { SIGN_IN_ERROR_CODES, type SignInErrorAction, type SignInErrorActionKind, type SignInErrorCode, SignInErrorPage, type SignInErrorPageProps, type SignInErrorPayload };

package/dist/errors/index.js

@@ -0,0 +1,46 @@
+import { Button } from '@godxjp/ui/general';
+import { ErrorSurface } from '@godxjp/ui/layout';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+
+// src/errors/types.ts
+var SIGN_IN_ERROR_CODES = [
+  // Sent by the IdP as `error_reason` on a refused /sso/authorize.
+  "organization_membership_missing",
+  "organization_unavailable",
+  "organization_context_missing",
+  "service_entitlement_missing",
+  "subscription_inactive",
+  "personal_workspace_not_enabled",
+  "user_inactive",
+  "user_unverified",
+  "service_unavailable",
+  "employee_onboarding",
+  // Raised on the consumer's side.
+  "access_denied",
+  "callback_invalid",
+  "token_exchange_failed",
+  "platform_unavailable",
+  "session_expired",
+  "forbidden",
+  "too_many_attempts"
+];
+function SignInErrorPage({ error }) {
+  const { action } = error;
+  return /* @__PURE__ */ jsx(
+    ErrorSurface,
+    {
+      mode: "system",
+      status: error.status,
+      title: error.title,
+      description: error.detail === null || error.detail === "" ? error.description : /* @__PURE__ */ jsxs(Fragment, { children: [
+        error.description,
+        " ",
+        /* @__PURE__ */ jsx("span", { "data-slot": "sign-in-error-detail", children: error.detail })
+      ] }),
+      requestId: error.request_id ?? void 0,
+      action: action === null ? null : /* @__PURE__ */ jsx(Button, { asChild: true, "data-action": action.kind, children: /* @__PURE__ */ jsx("a", { href: action.href, children: action.label }) })
+    }
+  );
+}
+
+export { SIGN_IN_ERROR_CODES, SignInErrorPage };

package/dist/laravel/index.js

@@ -22,6 +22,18 @@ var ApiError = class extends Error {
 // src/laravel/api-client.ts
 var UNREACHABLE = "Could not reach the server. Check your connection and try again.";
 var redirectingToSignIn = false;
+var liftsLatchOnRestore = false;
+function liftLatchOnRestore() {
+  if (liftsLatchOnRestore) {
+    return;
+  }
+  liftsLatchOnRestore = true;
+  window.addEventListener("pageshow", (event) => {
+    if (event.persisted) {
+      redirectingToSignIn = false;
+    }
+  });
+}
 function readCookie(name) {
   const prefix = `${name}=`;
   const entry = document.cookie.split("; ").find((cookie) => cookie.startsWith(prefix));
@@ -77,6 +89,7 @@ function redirectToSignIn(signInUrl) {
     return;
   }
   redirectingToSignIn = true;
+  liftLatchOnRestore();
   const { pathname, search } = window.location;
   window.location.assign(signInUrl(`${pathname}${search}`));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@godxjp/sdk",
-    "version": "0.5.0",
+    "version": "0.7.0",
     "description": "GoDX JavaScript SDK \u2014 shared frontend infrastructure for GoDX products.",
     "license": "Apache-2.0",
     "repository": {
@@ -24,6 +24,14 @@
             "types": "./dist/index.d.ts",
             "import": "./dist/index.js"
         },
+        "./agent": {
+            "types": "./dist/agent/index.d.ts",
+            "import": "./dist/agent/index.js"
+        },
+        "./errors": {
+            "types": "./dist/errors/index.d.ts",
+            "import": "./dist/errors/index.js"
+        },
         "./laravel": {
             "types": "./dist/laravel/index.d.ts",
             "import": "./dist/laravel/index.js"
@@ -41,6 +49,7 @@
         "test": "vitest run --typecheck"
     },
     "devDependencies": {
+        "@godxjp/ui": "^33.12.4",
         "@laravel/echo-react": "^2.5.0",
         "@types/node": "^22.10.2",
         "@types/react": "^19.3.0",
@@ -55,10 +64,14 @@
         "vitest": "^2.1.8"
     },
     "peerDependencies": {
+        "@godxjp/ui": ">=19.2.0 <34",
         "@laravel/echo-react": "^2.5.0",
         "react": "^19.3.0"
     },
     "peerDependenciesMeta": {
+        "@godxjp/ui": {
+            "optional": true
+        },
         "@laravel/echo-react": {
             "optional": true
         },