Reflex SDK

@stndrds/reflex-sdk is the surface a Reflex is written against. It carries one definition per capability, shared by three consumers, so a capability cannot mean two different things:

• the agent toolchain, which turns each definition into a tool an agent can call;
• the Reflex gateway, which uses each definition's kind to decide what a rehearsal captures;
• Reflex code, whose argument types are inferred from those same definitions.

The capabilities

Five, all scoped to a single record: get_record, search_records, create_record, update_record, delete_record. Bulk and unscoped tools are excluded on purpose — one bulk call mutates many records and would be reported as a single effect, which would make an effects report understate what happened.

The entry point

A Reflex version is a map of source files with index.ts as its entry. index.ts must default- export the function the runner calls, and defineReflex types it:

import { createReflexClient, defineReflex, isCapabilityError } from "@stndrds/reflex-sdk";

export default defineReflex(async (input: { recordId: string }) => {
  const contact = await createReflexClient().objects("contacts").get(input.recordId);
  return isCapabilityError(contact) ? null : contact.record.label;
});

The runner passes the invocation's payload as the single argument and keeps whatever the handler returns. Nothing validates the payload's shape — declare it and narrow it yourself.

Tenant types

Object and attribute types are not in the package. They are generated per tenant from that tenant's live schema and augment the TenantObjects interface the package declares. Load them and object names, attribute names and select option values are all checked:

import { createReflexClient } from "@stndrds/reflex-sdk";

const client = createReflexClient();
await client.objects("contacts").update(recordId, { status: "client" });

Without the generated file there are no object names to pass, so the call does not compile.

Results

Every write can return one of three things, and all three are in its type: the result, a { captured: true } marker when the run is a rehearsal, or { error } when the capability declined. Use isCaptured and isCapabilityError to narrow. Reading recordId off a rehearsal result is precisely the bug the union exists to prevent.

The gate

Before a version is promoted, the server compiles it against the SDK and the tenant's generated types with strict on, no DOM and no Node types in scope. A Reflex that compiles with the tenant types removed touches no tenant data, which is the condition for shipping it from a codebase rather than generating it per tenant.

Bundling

A version is compiled into a single JavaScript file before anything can run it. The bundler resolves every import at build time, so the runtime never installs a package and never resolves a module — a Reflex starts as fast as reading one file.

Only @stndrds/reflex-sdk may be imported. Relative imports between a version's own source files work normally; anything else — a Node builtin, a package that happens to be installed next to the server — is refused by name, with the name in the error.

Egress

The bundle is then parsed and checked for anything that could reach the network without going through the gateway a runner installs: fetch, XMLHttpRequest, WebSocket, require, eval, new Function, dynamic import(), .constructor, and any use of globalThis, window, self or global.

Each accepted version is stored with a sha256 digest of its bundle, which is what identifies the artefact a runner has already cached.

How a Reflex runs

A promoted version executes inside a sandbox that belongs to the workspace, not to the Reflex. The runner reconnects to that sandbox, writes the artefact under its digest if it is not already cached there, and starts the code with its input on standard input.

Every capability call the code makes leaves the sandbox on standard output and is answered by the gateway on standard input. Three consequences follow, and they are the point:

• The sandbox makes no network connection. A Reflex needs no outbound access to reach the platform, so a run cannot leave the machine by any route the runner provides.
• The sandbox holds no credential. The run token stays in the API process and is attached to each call there. There is nothing inside the sandbox worth stealing.
• The workspace, and the acting identity, come from the token — never from anything the code says.

A sandbox that the provider has reclaimed is not a failure: the artefact lives in the database, so the runner provisions a new one and writes it again.

An agent invokes a Reflex with one tool, call_reflex, which takes the Reflex's name and a payload and returns what it produced. That is the only Reflex tool an agent holds — reading or writing a Reflex's own code is a separate capability this milestone does not expose to an agent.