@raybase/create 0.3.13 → 0.3.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/skills/raybase-background-jobs/SKILL.md +26 -8
- package/skills/raybase-deploy/SKILL.md +20 -2
- package/skills/raybase-mcp/SKILL.md +12 -1
- package/templates/astro-emdash/src/worker-entry.ts +5 -2
- package/templates/react-router/workers/app.ts +5 -3
- package/templates/tanstack-start/src/worker-entry.ts +5 -2
package/package.json
CHANGED
|
@@ -351,6 +351,12 @@ Repeatable handlers must be safe when they run late or more than once:
|
|
|
351
351
|
operational rhythms.
|
|
352
352
|
- Use the Jobs admin UI to verify last run, next run, failures, retry/cancel,
|
|
353
353
|
and schedule visibility before handing off.
|
|
354
|
+
- Each failed attempt, and each run that ends failed without one (its lease
|
|
355
|
+
expired, or it was denied), also logs `console.error("raybase.job.failed",
|
|
356
|
+
{ job, runId, attempt, maxAttempts, retry })` for the Worker's logs and a
|
|
357
|
+
host's tail events. It never includes the input; set
|
|
358
|
+
`appConfig.jobs.logFailureMessages: true` only if the error messages hold
|
|
359
|
+
nothing private, since that adds them as `error`.
|
|
354
360
|
|
|
355
361
|
## Local Development
|
|
356
362
|
|
|
@@ -545,8 +551,7 @@ export const jobs = {
|
|
|
545
551
|
one when the parent can run more than once.
|
|
546
552
|
- Add a fan-out with `enqueueMany(batchId, job, items)`, where each item is
|
|
547
553
|
`{ input, idempotencyKey?, delay? }`, what `enqueue` takes for one child.
|
|
548
|
-
Every input is validated
|
|
549
|
-
before anything is written. Each chunk of 100 is then written in one data
|
|
554
|
+
Every input is validated before anything is written. Each chunk of 100 is then written in one data
|
|
550
555
|
Durable Object transaction, with its runs, enqueue events and audit rows,
|
|
551
556
|
and sent in one queue batch send. The call returns the runs in item order.
|
|
552
557
|
`enqueue` in a loop costs a Durable Object call and a queue send per
|
|
@@ -563,9 +568,9 @@ export const jobs = {
|
|
|
563
568
|
- Batches do not nest: `batches.create` inside a batch child throws, because
|
|
564
569
|
the outer batch would not wait for it. Chain stages from the continuation,
|
|
565
570
|
as above.
|
|
566
|
-
-
|
|
567
|
-
`
|
|
568
|
-
|
|
571
|
+
- A batch is the app's own code's: `create`, `enqueue`, `enqueueMany`,
|
|
572
|
+
`seal`, `cancel`, `get` and `children` check that the jobs are registered,
|
|
573
|
+
not their route policies.
|
|
569
574
|
- An operator retry of a continuation keeps `ctx.batch`; a retried child runs
|
|
570
575
|
on its own and does not rejoin the batch.
|
|
571
576
|
- `/admin` Jobs shows each batch's progress, runs, and continuation run.
|
|
@@ -691,6 +696,17 @@ job alone can occupy every invocation) and when the consumer sets no
|
|
|
691
696
|
|
|
692
697
|
## Policy Traps
|
|
693
698
|
|
|
699
|
+
- A job's policies say what a person may do over the jobs route, and nothing
|
|
700
|
+
else. `enqueue` is who may `POST /api/jobs/:name`, `view` who may read its
|
|
701
|
+
runs there (`enqueue` when omitted), and `cancel` who may
|
|
702
|
+
`POST /api/jobs/runs/:id/cancel`: operators only when omitted, never the
|
|
703
|
+
`enqueue` policy. An operator may always cancel from `/admin`.
|
|
704
|
+
- The app's own code (`ctx.jobs` in an action, route, tool, agent or job, and
|
|
705
|
+
`enqueueRaybaseJob`) books, schedules, reads and cancels without them: a
|
|
706
|
+
member's press may book a job whose `enqueue` is `denyAll`, and take its
|
|
707
|
+
schedule back, while that member can neither enqueue it over the route nor
|
|
708
|
+
cancel its runs. Guard who may press in the action's own `policy`.
|
|
709
|
+
|
|
694
710
|
- Scheduled and system jobs run as service principals. Service principals never
|
|
695
711
|
satisfy `role()` or `owns()`. Gate scheduled work with
|
|
696
712
|
`anyOf(role(appRoles, "operations"), fromService("scheduler"))`.
|
|
@@ -698,9 +714,11 @@ job alone can occupy every invocation) and when the consumer sets no
|
|
|
698
714
|
core it compares to `user.id`; in Pro it compares to membership id.
|
|
699
715
|
- `runAs` is only `"actor"`, `"system"`, or `{ userRef: "inputField" }`.
|
|
700
716
|
`userRef` must point to a string in the job input or enqueue fails.
|
|
701
|
-
-
|
|
702
|
-
|
|
703
|
-
does not run.
|
|
717
|
+
- A run is re-checked when the queue message runs. If the actor is disabled,
|
|
718
|
+
or a run the jobs route admitted no longer passes `enqueue`, the run is
|
|
719
|
+
marked denied and the handler does not run. A run the app's own code booked
|
|
720
|
+
(`admittedBy: "app"`) needs only its actor and `runAs` still present; a
|
|
721
|
+
schedule whose person is gone is cancelled when it falls due.
|
|
704
722
|
- Cancellation does not interrupt JavaScript. Handlers must check `ctx.signal`
|
|
705
723
|
at natural boundaries and return early.
|
|
706
724
|
- `mode: "workflow"` is not enabled in this Raybase version. Do not set it.
|
|
@@ -149,6 +149,24 @@ which limits sign-up to the people it names). `raybase secrets
|
|
|
149
149
|
list` explains each secret and `raybase secrets new` prints fresh values, by
|
|
150
150
|
kind, as JSON for `wrangler deploy --secrets-file`. `wrangler deploy` of the
|
|
151
151
|
build then works on any account.
|
|
152
|
-
The app applies its own database changes on first use.
|
|
153
|
-
|
|
152
|
+
The app applies its own database changes on first use.
|
|
153
|
+
|
|
154
|
+
A host that runs the app reaches it as itself, with no admin session, through
|
|
155
|
+
`fetch` with `props: { raybaseHost: true }` on the request's ExecutionContext
|
|
156
|
+
(`env.DISPATCHER.get(app, { props: { raybaseHost: true } })` from a Workers
|
|
157
|
+
for Platforms dispatcher, or `props` in a service binding's config). Only the
|
|
158
|
+
host's code sets `props`; a dispatcher must never copy request data into
|
|
159
|
+
them. `POST /__raybase/host/backup` then takes one backup and answers `200 {
|
|
160
|
+
key, bytes, date }`, `409 { error, code: "BACKUP_NOT_CONFIGURED" }` when
|
|
161
|
+
backups are off, unbound or keyless, or `503 { error, code }` when it fails;
|
|
162
|
+
without the prop the address answers as an unknown one. A host backup counts
|
|
163
|
+
toward `RAYBASE_BACKUPS_RETAIN` with the nightly and admin ones (trigger
|
|
164
|
+
`"host"`, audit `database.backup.host`). Keep `isRaybaseHostRequest(request,
|
|
165
|
+
ctx)` in the worker entry, ahead of the framework, as the templates have it;
|
|
166
|
+
`raybase doctor` warns (`host-routing`) when it is missing. Each failed job
|
|
167
|
+
attempt, and each run that ends failed without one (lease expired, denied),
|
|
168
|
+
logs `console.error("raybase.job.failed", { job, runId, attempt, maxAttempts,
|
|
169
|
+
retry })`, never with the input, and with the error's message only under
|
|
170
|
+
`appConfig.jobs.logFailureMessages: true`. See the
|
|
171
|
+
hosting guide (`docs/hosting.md` on the Raybase site) for the full contract.
|
|
154
172
|
|
|
@@ -134,7 +134,8 @@ OAuth registration mode.
|
|
|
134
134
|
Browser-less clients (CLIs on remote machines, CI, bring-your-own agents) use
|
|
135
135
|
the `client_credentials` grant. A signed-in user registers a confidential
|
|
136
136
|
client at `/api/auth/oauth/register` with `grant_types: ["client_credentials"]`
|
|
137
|
-
and the `scope` it may hold
|
|
137
|
+
and the `scope` it may hold (what a person may grant; see Scopes); the
|
|
138
|
+
one-time `client_secret` in the response is
|
|
138
139
|
the only time the secret is shown. The client mints access tokens with
|
|
139
140
|
`grant_type=client_credentials` and HTTP Basic (`client_secret_basic`, the
|
|
140
141
|
default) or form (`client_secret_post`) authentication, may narrow but never
|
|
@@ -261,6 +262,16 @@ the `io.modelcontextprotocol/ui` extension and accept
|
|
|
261
262
|
- Mutating tools default to `mcp:write` plus `mcp:tool:<name>`.
|
|
262
263
|
- Resources default to `mcp:read`.
|
|
263
264
|
- Set explicit `scopes` only when a narrower or custom grant is required.
|
|
265
|
+
- What a grant may hold depends on who grants it. A person (approving an agent
|
|
266
|
+
at consent, or registering their own key) may grant `mcp:read`, `mcp:write`
|
|
267
|
+
and scopes that only narrow them: ones every tool or resource lists beside
|
|
268
|
+
`mcp:read` or `mcp:write`, such as Raybase's `mcp:tool:<name>`. A custom
|
|
269
|
+
scope a tool lists alone (`scopes: ["acme:platform"]`) hides the tool from
|
|
270
|
+
every agent a person approves; only the app's own server code grants it,
|
|
271
|
+
through a machine credential (`createMcpMachineCredential` with
|
|
272
|
+
`mcpAppConnectorScopeOptions()`, or Pro's `createRaybaseMachineCredential`).
|
|
273
|
+
Registration, consent and the token endpoint answer any other scope with
|
|
274
|
+
`invalid_scope`.
|
|
264
275
|
- Operator scopes must stay on Operator MCP. App MCP grants must never request
|
|
265
276
|
`operator:*` scopes.
|
|
266
277
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import serverEntry from "@tanstack/react-start/server-entry";
|
|
2
|
-
import { isRaybaseAdminPanelRequestDisabled, isRaybaseConnectorRequest, withRaybaseExecutionContext, withRaybaseLocalDevChrome, type RaybaseEnv } from "@raybase/core/worker";
|
|
2
|
+
import { isRaybaseAdminPanelRequestDisabled, isRaybaseConnectorRequest, isRaybaseHostRequest, withRaybaseExecutionContext, withRaybaseLocalDevChrome, type RaybaseEnv } from "@raybase/core/worker";
|
|
3
3
|
import { appConfig } from "./raybase.config";
|
|
4
4
|
import { raybaseHandler } from "./raybase.server";
|
|
5
5
|
|
|
@@ -11,7 +11,10 @@ export default {
|
|
|
11
11
|
if (isRaybaseAdminPanelRequestDisabled(request, appConfig)) return new Response("Not Found", { status: 404 });
|
|
12
12
|
// The connector (/mcp) and the discovery documents under /.well-known are
|
|
13
13
|
// Raybase's; the app's own routes never see them.
|
|
14
|
-
|
|
14
|
+
// So are the host's own requests (/__raybase/host/*, with
|
|
15
|
+
// ctx.props.raybaseHost set by the host's code); without that prop the
|
|
16
|
+
// address is the app's like any other.
|
|
17
|
+
if (isRaybaseConnectorRequest(request, appConfig) || isRaybaseHostRequest(request, ctx)) {
|
|
15
18
|
if (!raybaseHandler.fetch) throw new Error("Raybase handler is not fetch-compatible");
|
|
16
19
|
return raybaseHandler.fetch(request as never, env as never, ctx as never);
|
|
17
20
|
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { createRequestHandler } from "react-router";
|
|
2
|
-
import { withRaybaseLocalDevChrome } from "@raybase/core/worker";
|
|
2
|
+
import { isRaybaseHostRequest, withRaybaseLocalDevChrome } from "@raybase/core/worker";
|
|
3
3
|
import { appConfig, handleRaybaseRequest, isDisabledRaybaseAdminRequest, isRaybaseRequest, raybaseHandler } from "../app/raybase.server";
|
|
4
4
|
|
|
5
5
|
// Singleton Raybase SQLite Durable Object (bound as RAYBASE_DATA in wrangler.jsonc).
|
|
@@ -25,9 +25,11 @@ export default {
|
|
|
25
25
|
if (isDisabledRaybaseAdminRequest(request)) return new Response("Not Found", { status: 404 });
|
|
26
26
|
// Raybase (admin panel, auth pages, data API, MCP) and the React Router
|
|
27
27
|
// app share this worker; Raybase owns its path prefixes, React Router
|
|
28
|
-
// takes the rest.
|
|
28
|
+
// takes the rest. The host's own requests (/__raybase/host/*, with
|
|
29
|
+
// ctx.props.raybaseHost set by the host's code) are Raybase's too;
|
|
30
|
+
// without that prop the address is React Router's like any other.
|
|
29
31
|
const url = new URL(request.url);
|
|
30
|
-
if (isRaybaseRequest(url)) return handleRaybaseRequest(request, env, ctx);
|
|
32
|
+
if (isRaybaseRequest(url) || isRaybaseHostRequest(request, ctx)) return handleRaybaseRequest(request, env, ctx);
|
|
31
33
|
const response = await requestHandler(request, { cloudflare: { env, ctx } });
|
|
32
34
|
// Adds Raybase's local dev chrome (persona switcher) to app pages in
|
|
33
35
|
// local development; a no-op everywhere else.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import serverEntry from "@tanstack/react-start/server-entry";
|
|
2
|
-
import { isRaybaseAdminPanelRequestDisabled, isRaybaseConnectorRequest, withRaybaseExecutionContext, withRaybaseLocalDevChrome, type RaybaseEnv } from "@raybase/core/worker";
|
|
2
|
+
import { isRaybaseAdminPanelRequestDisabled, isRaybaseConnectorRequest, isRaybaseHostRequest, withRaybaseExecutionContext, withRaybaseLocalDevChrome, type RaybaseEnv } from "@raybase/core/worker";
|
|
3
3
|
import { appConfig } from "./raybase.config";
|
|
4
4
|
import { raybaseHandler } from "./raybase.server";
|
|
5
5
|
|
|
@@ -11,7 +11,10 @@ export default {
|
|
|
11
11
|
if (isRaybaseAdminPanelRequestDisabled(request, appConfig)) return new Response("Not Found", { status: 404 });
|
|
12
12
|
// The connector (/mcp) and its discovery documents (/.well-known/oauth-*)
|
|
13
13
|
// are Raybase's; the app's own routes never see them.
|
|
14
|
-
|
|
14
|
+
// So are the host's own requests (/__raybase/host/*, with
|
|
15
|
+
// ctx.props.raybaseHost set by the host's code); without that prop the
|
|
16
|
+
// address is the app's like any other.
|
|
17
|
+
if (isRaybaseConnectorRequest(request, appConfig) || isRaybaseHostRequest(request, ctx)) {
|
|
15
18
|
if (!raybaseHandler.fetch) throw new Error("Raybase handler is not fetch-compatible");
|
|
16
19
|
return raybaseHandler.fetch(request as never, env as never, ctx as never);
|
|
17
20
|
}
|