service

Credit-metered service invoke, buffered or streamed.

require("@builtin::modules.api.engine.service") -- service (also available as global 'service')

The service namespace: 23 functions.

globals/service/authenticated

service.authenticated() -> boolean

Whether a platform identity (JWT) is available to attach to service calls. Returns only a boolean — never the token.

Returns boolean — True if a caller identity is available.

if not service.authenticated() then error("link ZeroMind") end

globals/service/balance

service.balance() -> PromiseHandle?

Read the caller's credit balance from ZeroMind. Returns a promise handle for task.await() resolving the balance JSON, or nil when the gateway is unconfigured or no caller identity is available.

Returns PromiseHandle? — Promise handle for task.await(), or nil if not ready.

local h = service.balance(); local raw = h and task.await(h)

globals/service/gatewayConfigured

service.gatewayConfigured() -> boolean

Whether the ZeroMind service gateway has been configured. Service handlers use this to distinguish "gateway not configured" from "not signed in" when invoke returns nil.

Returns boolean — True if the gateway base URL is set.

if not service.gatewayConfigured() then error("no gateway") end

globals/service/invoke

service.invoke(offering: string, endpoint: string, opts: InvokeOpts?) -> PromiseHandle?

Invoke a provider offering's logical endpoint through ZeroMind. Returns a promise handle for task.await() resolving the InvokeResponse JSON, or nil when the gateway is unconfigured or no caller identity is available. The JWT and real upstream URL are never exposed to Luau.

Parameters

• offering string — Fully-qualified offering identity provider/name (e.g. "origozero/mesh_gen").
• endpoint string — Logical endpoint name (e.g. "create_preview").
• opts InvokeOpts (optional) — { params?, headers?, body?, idempotency_key? }.

Returns PromiseHandle? — Promise handle for task.await(), or nil if not ready.

local h = service.invoke("origozero/mesh_gen", "create_preview", { body = { prompt = p } })

globals/service/invokeStream

service.invokeStream(offering: string, endpoint: string, opts: StreamOpts) -> ServiceStream?

Invoke a provider offering's logical endpoint as a stream. ZeroMind relays the upstream's server-sent events as they arrive, then ends with a zeromind.settled event whose data is {"charged":N,"balance":M}, or a zeromind.failed event whose data is {"reason":...} when the relay stopped early. A call it refuses before the stream starts arrives as one zeromind.refused event carrying the HTTP status and the JSON answer as data; a call that could not be made, or a stream that broke or went quiet, arrives as zeromind.failed. Returns a stream at once, or nil when the gateway is unconfigured or no caller identity is available, exactly as invoke. Take events with stream:poll() (never waits) or stream:read() (waits for the next event; nil at the end), and release the connection with stream:close(). opts takes what invoke takes, plus a required idempotency_key that is unique to this call (ZeroMind refuses a key a streamed call already used) and an optional timeout_ms bounding the wait for the response head and for each next chunk (default 120000). The JWT and the real upstream URL are never exposed to Luau.

Parameters

• offering string — Fully-qualified offering identity provider/name (e.g. "origozero/llm").
• endpoint string — Logical endpoint name (e.g. "chat").
• opts StreamOpts — { params?, headers?, body?, idempotency_key, timeout_ms? }.

Returns ServiceStream? — A stream, or nil if not ready.

local s = service.invokeStream("origozero/llm", "chat", { body = { messages = msgs }, idempotency_key = id })
while s do local ev = s:read(); if ev == nil then break end; print(ev.event, ev.data) end

globals/service/jobStatus

service.jobStatus(jobId: string) -> PromiseHandle?

Poll a submitted service job. Returns a promise handle for task.await() resolving the JobStatusResponse JSON { job_id, status, result?, error? }: status walks pending/running -> succeeded (with result, the same InvokeResponse invoke returns) or failed (with error). nil when the gateway is unconfigured or no caller identity is available.

Parameters

• jobId string — Job id returned by submitJob.

Returns PromiseHandle? — Promise handle resolving the job status JSON, or nil if not ready.

local h = service.jobStatus(jobId); local raw = h and task.await(h)

globals/service/submitJob

service.submitJob(offering: string, endpoint: string, opts: InvokeOpts?) -> PromiseHandle?

Submit a durable async invocation of an offering endpoint. Same arguments as invoke, but the provider round-trip runs server-side (off this connection), so a slow synchronous provider or a dropped link no longer loses the result. Returns a promise handle for task.await() resolving { job_id, status }; poll it with jobStatus. nil when the gateway is unconfigured or no caller identity is available.

Parameters

• offering string — Fully-qualified offering identity provider/name (e.g. "origozero/mesh_gen").
• endpoint string — Logical endpoint name (e.g. "create_preview").
• opts InvokeOpts (optional) — { params?, headers?, body?, idempotency_key? }.

Returns PromiseHandle? — Promise handle resolving { job_id, status }, or nil if not ready.

local h = service.submitJob("origozero/mesh_gen", "create_preview", { body = { prompt = p } })

modules/service/authenticated

authenticated(): boolean

Whether a platform identity (JWT) is available to attach to service calls. Returns only a boolean — never the token.

if not service.authenticated() then error("link ZeroMind") end

modules/service/balance

balance(): PromiseHandle?

Read the caller's credit balance from ZeroMind. Returns a promise handle for task.await() resolving the balance JSON, or nil when the gateway is unconfigured or no caller identity is available.

local h = service.balance(); local raw = h and task.await(h)

modules/service/configureGateway

configureGateway(baseUrl: string, tokenIssuer: string?): boolean

TRUSTED ONLY. Set the ZeroMind base URL that service.invoke, service.balance and a trusted plugin's service calls target, and the issuer the JWTs it mints name as iss. The trusted-VM auth bootstrap calls this with the resolved issuer and token issuer.

Parameters

• baseUrl string — ZeroMind base URL (e.g. "https://origozero.ai").
• tokenIssuer string? (optional) — The iss the base URL's JWTs carry (optional; e.g. "https://api.origozero.ai"). Omitted, the base URL signs its own.

service.configureGateway("https://origozero.ai", "https://api.origozero.ai")

modules/service/configureWorld

configureWorld(guid: string): boolean

TRUSTED ONLY. Set the bound world guid attached to metered service invocations, so the credit ledger attributes each charge to the world it happened in. The trusted-VM world-load hook calls this on every bind so a runtime world switch re-points attribution.

Parameters

• guid string — The bound world's guid.

service.configureWorld(world.guid())

modules/service/gatewayConfigured

gatewayConfigured(): boolean

Whether the ZeroMind service gateway has been configured. Service handlers use this to distinguish "gateway not configured" from "not signed in" when invoke returns nil.

if not service.gatewayConfigured() then error("no gateway") end

modules/service/invoke

invoke(offering: string, endpoint: string, opts: InvokeOpts?): PromiseHandle?

Invoke a provider offering's logical endpoint through ZeroMind. Returns a promise handle for task.await() resolving the InvokeResponse JSON, or nil when the gateway is unconfigured or no caller identity is available. The JWT and real upstream URL are never exposed to Luau.

Parameters

• offering string — Fully-qualified offering identity provider/name (e.g. "origozero/mesh_gen").
• endpoint string — Logical endpoint name (e.g. "create_preview").
• opts InvokeOpts? (optional) — { params?, headers?, body?, idempotency_key? }.

local h = service.invoke("origozero/mesh_gen", "create_preview", { body = { prompt = p } })

modules/service/invokeStream

invokeStream(offering: string, endpoint: string, opts: StreamOpts): ServiceStream?

Invoke a provider offering's logical endpoint as a stream. ZeroMind relays the upstream's server-sent events as they arrive, then ends with a zeromind.settled event whose data is {"charged":N,"balance":M}, or a zeromind.failed event whose data is {"reason":...} when the relay stopped early. A call it refuses before the stream starts arrives as one zeromind.refused event carrying the HTTP status and the JSON answer as data; a call that could not be made, or a stream that broke or went quiet, arrives as zeromind.failed. Returns a stream at once, or nil when the gateway is unconfigured or no caller identity is available, exactly as invoke. Take events with stream:poll() (never waits) or stream:read() (waits for the next event; nil at the end), and release the connection with stream:close(). opts takes what invoke takes, plus a required idempotency_key that is unique to this call (ZeroMind refuses a key a streamed call already used) and an optional timeout_ms bounding the wait for the response head and for each next chunk (default 120000). The JWT and the real upstream URL are never exposed to Luau.

Parameters

• offering string — Fully-qualified offering identity provider/name (e.g. "origozero/llm").
• endpoint string — Logical endpoint name (e.g. "chat").
• opts StreamOpts — { params?, headers?, body?, idempotency_key, timeout_ms? }.

local s = service.invokeStream("origozero/llm", "chat", { body = { messages = msgs }, idempotency_key = id })
while s do local ev = s:read(); if ev == nil then break end; print(ev.event, ev.data) end

modules/service/jobStatus

jobStatus(jobId: string): PromiseHandle?

Poll a submitted service job. Returns a promise handle for task.await() resolving the JobStatusResponse JSON { job_id, status, result?, error? }: status walks pending/running -> succeeded (with result, the same InvokeResponse invoke returns) or failed (with error). nil when the gateway is unconfigured or no caller identity is available.

Parameters

• jobId string — Job id returned by submitJob.

local h = service.jobStatus(jobId); local raw = h and task.await(h)

modules/service/submitJob

submitJob(offering: string, endpoint: string, opts: InvokeOpts?): PromiseHandle?

Submit a durable async invocation of an offering endpoint. Same arguments as invoke, but the provider round-trip runs server-side (off this connection), so a slow synchronous provider or a dropped link no longer loses the result. Returns a promise handle for task.await() resolving { job_id, status }; poll it with jobStatus. nil when the gateway is unconfigured or no caller identity is available.

Parameters

• offering string — Fully-qualified offering identity provider/name (e.g. "origozero/mesh_gen").
• endpoint string — Logical endpoint name (e.g. "create_preview").
• opts InvokeOpts? (optional) — { params?, headers?, body?, idempotency_key? }.

local h = service.submitJob("origozero/mesh_gen", "create_preview", { body = { prompt = p } })

typed/builtin//modules/api/engine/service/service/authenticated

service.authenticated() -> boolean

Whether a platform identity (JWT) is available to attach to service calls. Returns only a boolean — never the token.

Returns boolean — True if a caller identity is available.

if not service.authenticated() then error("link ZeroMind") end

typed/builtin//modules/api/engine/service/service/balance

service.balance() -> PromiseHandle?

Read the caller's credit balance from ZeroMind. Returns a promise handle for task.await() resolving the balance JSON, or nil when the gateway is unconfigured or no caller identity is available.

Returns PromiseHandle? — Promise handle for task.await(), or nil if not ready.

local h = service.balance(); local raw = h and task.await(h)

typed/builtin//modules/api/engine/service/service/gatewayConfigured

service.gatewayConfigured() -> boolean

Whether the ZeroMind service gateway has been configured. Service handlers use this to distinguish "gateway not configured" from "not signed in" when invoke returns nil.

Returns boolean — True if the gateway base URL is set.

if not service.gatewayConfigured() then error("no gateway") end

typed/builtin//modules/api/engine/service/service/invoke

service.invoke(offering: string, endpoint: string, opts: InvokeOpts?) -> PromiseHandle?

Invoke a provider offering's logical endpoint through ZeroMind. Returns a promise handle for task.await() resolving the InvokeResponse JSON, or nil when the gateway is unconfigured or no caller identity is available. The JWT and real upstream URL are never exposed to Luau.

Parameters

• offering string — Fully-qualified offering identity provider/name (e.g. "origozero/mesh_gen").
• endpoint string — Logical endpoint name (e.g. "create_preview").
• opts InvokeOpts (optional) — { params?, headers?, body?, idempotency_key? }.

Returns PromiseHandle? — Promise handle for task.await(), or nil if not ready.

local h = service.invoke("origozero/mesh_gen", "create_preview", { body = { prompt = p } })

typed/builtin//modules/api/engine/service/service/invokeStream

service.invokeStream(offering: string, endpoint: string, opts: StreamOpts) -> ServiceStream?

Invoke a provider offering's logical endpoint as a stream. ZeroMind relays the upstream's server-sent events as they arrive, then ends with a zeromind.settled event whose data is {"charged":N,"balance":M}, or a zeromind.failed event whose data is {"reason":...} when the relay stopped early. A call it refuses before the stream starts arrives as one zeromind.refused event carrying the HTTP status and the JSON answer as data; a call that could not be made, or a stream that broke or went quiet, arrives as zeromind.failed. Returns a stream at once, or nil when the gateway is unconfigured or no caller identity is available, exactly as invoke. Take events with stream:poll() (never waits) or stream:read() (waits for the next event; nil at the end), and release the connection with stream:close(). opts takes what invoke takes, plus a required idempotency_key that is unique to this call (ZeroMind refuses a key a streamed call already used) and an optional timeout_ms bounding the wait for the response head and for each next chunk (default 120000). The JWT and the real upstream URL are never exposed to Luau.

Parameters

• offering string — Fully-qualified offering identity provider/name (e.g. "origozero/llm").
• endpoint string — Logical endpoint name (e.g. "chat").
• opts StreamOpts — { params?, headers?, body?, idempotency_key, timeout_ms? }.

Returns ServiceStream? — A stream, or nil if not ready.

local s = service.invokeStream("origozero/llm", "chat", { body = { messages = msgs }, idempotency_key = id })
while s do local ev = s:read(); if ev == nil then break end; print(ev.event, ev.data) end

typed/builtin//modules/api/engine/service/service/jobStatus

service.jobStatus(jobId: string) -> PromiseHandle?

Poll a submitted service job. Returns a promise handle for task.await() resolving the JobStatusResponse JSON { job_id, status, result?, error? }: status walks pending/running -> succeeded (with result, the same InvokeResponse invoke returns) or failed (with error). nil when the gateway is unconfigured or no caller identity is available.

Parameters

• jobId string — Job id returned by submitJob.

Returns PromiseHandle? — Promise handle resolving the job status JSON, or nil if not ready.

local h = service.jobStatus(jobId); local raw = h and task.await(h)

typed/builtin//modules/api/engine/service/service/submitJob

service.submitJob(offering: string, endpoint: string, opts: InvokeOpts?) -> PromiseHandle?

Submit a durable async invocation of an offering endpoint. Same arguments as invoke, but the provider round-trip runs server-side (off this connection), so a slow synchronous provider or a dropped link no longer loses the result. Returns a promise handle for task.await() resolving { job_id, status }; poll it with jobStatus. nil when the gateway is unconfigured or no caller identity is available.

Parameters

• offering string — Fully-qualified offering identity provider/name (e.g. "origozero/mesh_gen").
• endpoint string — Logical endpoint name (e.g. "create_preview").
• opts InvokeOpts (optional) — { params?, headers?, body?, idempotency_key? }.

Returns PromiseHandle? — Promise handle resolving { job_id, status }, or nil if not ready.

local h = service.submitJob("origozero/mesh_gen", "create_preview", { body = { prompt = p } })