@fungi.computer/oyster 0.10.0 → 0.11.0
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/README.md +33 -2
- package/dist/agents.d.ts +66 -22
- package/dist/agents.js +128 -38
- package/dist/authorization.d.ts +25 -3
- package/dist/authorization.js +47 -14
- package/dist/browser/capability-source.d.ts +23 -5
- package/dist/browser/capability-source.js +19 -22
- package/dist/browser/index.d.ts +2 -1
- package/dist/browser/index.js +1 -0
- package/dist/browser/live-view.d.ts +38 -0
- package/dist/browser/live-view.js +179 -0
- package/dist/channels/binding.d.ts +2 -0
- package/dist/channels/run-decision.d.ts +33 -0
- package/dist/channels/run-decision.js +25 -0
- package/dist/channels/visitor-channel.d.ts +84 -14
- package/dist/channels/visitor-channel.js +55 -32
- package/dist/channels/visitor-edge.d.ts +18 -2
- package/dist/channels/visitor-edge.js +67 -5
- package/dist/channels/visitors.d.ts +4 -0
- package/dist/channels/visitors.js +22 -1
- package/dist/channels/web-binding.d.ts +117 -0
- package/dist/channels/web-binding.js +227 -0
- package/dist/embed-metafiles.d.ts +8 -0
- package/dist/embed-metafiles.js +2 -0
- package/dist/embed-scripts.d.ts +8 -0
- package/dist/embed-scripts.js +3 -0
- package/dist/host.d.ts +3 -1
- package/dist/host.js +6 -1
- package/dist/page/embed-challenge.d.ts +19 -0
- package/dist/page/embed-challenge.js +45 -0
- package/dist/page/embed-error.d.ts +2 -0
- package/dist/page/embed-error.js +16 -0
- package/dist/page/embed-loader-protocol.d.ts +12 -0
- package/dist/page/embed-loader-protocol.js +29 -0
- package/dist/standalone/agent-connections.d.ts +22 -19
- package/dist/standalone/agent-connections.js +150 -106
- package/dist/standalone/agents.d.ts +168 -14
- package/dist/standalone/agents.js +310 -17
- package/dist/standalone/browser.d.ts +14 -2
- package/dist/standalone/browser.js +52 -4
- package/dist/standalone/channel-session-door.d.ts +4 -0
- package/dist/standalone/channel-session-door.js +72 -0
- package/dist/standalone/owner-routes.d.ts +4 -3
- package/dist/standalone/owner-routes.js +7 -1
- package/dist/standalone/visitor-edge.d.ts +36 -0
- package/dist/standalone/visitor-edge.js +67 -0
- package/dist/standalone/visitor-proof.d.ts +23 -0
- package/dist/standalone/visitor-proof.js +67 -0
- package/dist/standalone/website-channels.d.ts +134 -0
- package/dist/standalone/website-channels.js +262 -0
- package/dist/standalone/worker-routes.d.ts +4 -1
- package/dist/standalone/worker-routes.js +3 -0
- package/dist/standalone/worker.d.ts +2 -1
- package/dist/standalone/worker.js +4 -0
- package/dist/testing/capabilities.d.ts +3 -0
- package/dist/testing/capabilities.js +1 -0
- package/dist/testing/installation.d.ts +4 -2
- package/dist/testing/installation.js +7 -2
- package/dist/workers-git.js +2 -2
- package/docs/api/agents.md +103 -36
- package/docs/api/browser.md +115 -8
- package/docs/api/workers-git.md +6 -6
- package/package.json +31 -6
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { channelIds } from "./ids.js";
|
|
3
|
+
import { webOriginSchema } from "@fungi.computer/nacre/website-channels";
|
|
4
|
+
/**
|
|
5
|
+
* The website channel's neutral binding rules: what a site key, its allowed
|
|
6
|
+
* origins and its accent are, how an owner's edit changes them, and the fixed
|
|
7
|
+
* words every website Agent starts from. Team, billing and member authority
|
|
8
|
+
* stay with the host that stores the binding.
|
|
9
|
+
*/
|
|
10
|
+
/** Owner-set widget accent: exactly `#rrggbb`, stored lowercase. */
|
|
11
|
+
export const hexColorSchema = z
|
|
12
|
+
.string()
|
|
13
|
+
.regex(/^#[0-9a-f]{6}$/iu, "Accent must be #rrggbb")
|
|
14
|
+
.transform((value) => value.toLowerCase());
|
|
15
|
+
const siteKeySchema = z
|
|
16
|
+
.string()
|
|
17
|
+
.refine((value) => channelIds.site.is(value), "Invalid site key");
|
|
18
|
+
const originsSchema = z.array(webOriginSchema).min(1).max(16);
|
|
19
|
+
/** The exact selector of a web binding; the site key is how the embed finds it. */
|
|
20
|
+
export const webSelectorSchema = z.strictObject({
|
|
21
|
+
provider: z.literal("web"),
|
|
22
|
+
siteKey: siteKeySchema,
|
|
23
|
+
origins: originsSchema,
|
|
24
|
+
accent: hexColorSchema.optional(),
|
|
25
|
+
/** Visitors must pass a Turnstile check before a mint; absent means off. */
|
|
26
|
+
turnstile: z.boolean().optional(),
|
|
27
|
+
});
|
|
28
|
+
/** Owner input for a new web selector. The site key is minted, never supplied. */
|
|
29
|
+
export const webSelectorRequestSchema = z.strictObject({
|
|
30
|
+
provider: z.literal("web"),
|
|
31
|
+
origins: originsSchema,
|
|
32
|
+
accent: hexColorSchema.optional(),
|
|
33
|
+
turnstile: z.boolean().optional(),
|
|
34
|
+
});
|
|
35
|
+
/** The edits an owner may make to a web selector. */
|
|
36
|
+
export const webSelectorEditSchema = z.strictObject({
|
|
37
|
+
origins: originsSchema.optional(),
|
|
38
|
+
/** `null` clears the accent back to the embed theme default. */
|
|
39
|
+
accent: hexColorSchema.nullable().optional(),
|
|
40
|
+
turnstile: z.boolean().optional(),
|
|
41
|
+
/** Mint a new site key; the old key stops resolving at once. */
|
|
42
|
+
rotateSiteKey: z.literal(true).optional(),
|
|
43
|
+
});
|
|
44
|
+
/** Does this edit touch the web selector at all? */
|
|
45
|
+
export function editsWebSelector(edit) {
|
|
46
|
+
return (edit.origins !== undefined ||
|
|
47
|
+
edit.accent !== undefined ||
|
|
48
|
+
edit.turnstile !== undefined ||
|
|
49
|
+
edit.rotateSiteKey !== undefined);
|
|
50
|
+
}
|
|
51
|
+
/** Mint the selector of a new web binding. */
|
|
52
|
+
export function mintWebSelector(requested) {
|
|
53
|
+
const selector = {
|
|
54
|
+
provider: "web",
|
|
55
|
+
siteKey: channelIds.site.generate(),
|
|
56
|
+
origins: requested.origins,
|
|
57
|
+
};
|
|
58
|
+
if (requested.accent !== undefined)
|
|
59
|
+
selector.accent = requested.accent;
|
|
60
|
+
if (requested.turnstile === true)
|
|
61
|
+
selector.turnstile = true;
|
|
62
|
+
return selector;
|
|
63
|
+
}
|
|
64
|
+
/** Apply one owner edit to a selector; unmentioned facts are unchanged. */
|
|
65
|
+
export function editWebSelector(selector, edit) {
|
|
66
|
+
const next = {
|
|
67
|
+
provider: "web",
|
|
68
|
+
siteKey: edit.rotateSiteKey === true
|
|
69
|
+
? channelIds.site.generate()
|
|
70
|
+
: selector.siteKey,
|
|
71
|
+
origins: edit.origins ?? selector.origins,
|
|
72
|
+
};
|
|
73
|
+
const accent = edit.accent === undefined ? selector.accent : edit.accent;
|
|
74
|
+
if (accent !== null && accent !== undefined)
|
|
75
|
+
next.accent = accent;
|
|
76
|
+
const turnstile = edit.turnstile ?? selector.turnstile;
|
|
77
|
+
if (turnstile === true)
|
|
78
|
+
next.turnstile = true;
|
|
79
|
+
return next;
|
|
80
|
+
}
|
|
81
|
+
/** Fixed rules that precede every channel persona. */
|
|
82
|
+
const CHANNEL_PREAMBLE = [
|
|
83
|
+
"You are an Agent answering on a channel on behalf of your owner.",
|
|
84
|
+
"Stay on the owner's topic. Never claim an action you did not take; only report work confirmed by returned results.",
|
|
85
|
+
"When you are unsure or the party asks for a person, say that you will pass the conversation to the owner.",
|
|
86
|
+
].join(" ");
|
|
87
|
+
/** The fixed preamble, then the owner's persona for a person-facing channel. */
|
|
88
|
+
export function personChannelInstructions(persona) {
|
|
89
|
+
const trimmed = persona.trim();
|
|
90
|
+
return trimmed.length === 0
|
|
91
|
+
? CHANNEL_PREAMBLE
|
|
92
|
+
: `${CHANNEL_PREAMBLE}\n\nOwner persona:\n${trimmed}`;
|
|
93
|
+
}
|
|
94
|
+
/** A standalone website: one owner's Agent behind one site key. */
|
|
95
|
+
export const websiteBindingSchema = z.strictObject({
|
|
96
|
+
bindingId: z
|
|
97
|
+
.string()
|
|
98
|
+
.refine((value) => channelIds.binding.is(value), "Invalid binding"),
|
|
99
|
+
agentId: z.string().min(1).max(256),
|
|
100
|
+
selector: webSelectorSchema,
|
|
101
|
+
lifecycle: z.enum(["active", "suspended"]),
|
|
102
|
+
/** Increments on every owner edit of this binding. */
|
|
103
|
+
authorityVersion: z.number().int().positive(),
|
|
104
|
+
/** Owner persona text, placed after the fixed channel preamble. */
|
|
105
|
+
persona: z.string().max(4_000),
|
|
106
|
+
});
|
|
107
|
+
/** Owner input for a new website. */
|
|
108
|
+
export const createWebsiteInputSchema = z.strictObject({
|
|
109
|
+
agentId: z.string().min(1).max(256),
|
|
110
|
+
selector: webSelectorRequestSchema,
|
|
111
|
+
persona: z.string().max(4_000).default(""),
|
|
112
|
+
});
|
|
113
|
+
/** Owner edit of one website, fenced by the version the owner last read. */
|
|
114
|
+
export const updateWebsiteInputSchema = webSelectorEditSchema.extend({
|
|
115
|
+
expectedVersion: z.number().int().positive(),
|
|
116
|
+
persona: z.string().max(4_000).optional(),
|
|
117
|
+
lifecycle: z.enum(["active", "suspended"]).optional(),
|
|
118
|
+
});
|
|
119
|
+
/** Closed owner failures; routes map each to one status. */
|
|
120
|
+
export class WebsiteBindingError extends Error {
|
|
121
|
+
code;
|
|
122
|
+
constructor(code) {
|
|
123
|
+
super(code);
|
|
124
|
+
this.code = code;
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
const payloadRow = z.strictObject({ payload: z.string() });
|
|
128
|
+
const receiptRow = payloadRow.extend({ input_json: z.string().nullable() });
|
|
129
|
+
const requestIdSchema = z.string().min(1).max(128);
|
|
130
|
+
/**
|
|
131
|
+
* One standalone owner's website bindings, behind a SQL port. The owner
|
|
132
|
+
* authorizes the caller; this module fences versions and mints site keys.
|
|
133
|
+
*/
|
|
134
|
+
export function createWebsiteBindings(options) {
|
|
135
|
+
const { sql } = options;
|
|
136
|
+
const ensure = () => {
|
|
137
|
+
sql.exec(`CREATE TABLE IF NOT EXISTS oyster_website_bindings (
|
|
138
|
+
binding_id TEXT PRIMARY KEY,
|
|
139
|
+
agent_id TEXT NOT NULL,
|
|
140
|
+
site_key TEXT NOT NULL UNIQUE,
|
|
141
|
+
request_id TEXT UNIQUE,
|
|
142
|
+
input_json TEXT,
|
|
143
|
+
payload TEXT NOT NULL
|
|
144
|
+
) STRICT`);
|
|
145
|
+
};
|
|
146
|
+
const decode = (raw) => websiteBindingSchema.parse(JSON.parse(raw.payload));
|
|
147
|
+
const read = (bindingId) => {
|
|
148
|
+
ensure();
|
|
149
|
+
const row = sql
|
|
150
|
+
.exec("SELECT payload FROM oyster_website_bindings WHERE binding_id=?", bindingId)
|
|
151
|
+
.toArray()[0];
|
|
152
|
+
return row === undefined ? null : decode(payloadRow.parse(row));
|
|
153
|
+
};
|
|
154
|
+
return {
|
|
155
|
+
read,
|
|
156
|
+
/** The only way a public site key resolves; a rotated key does not. */
|
|
157
|
+
readBySiteKey: (siteKey) => {
|
|
158
|
+
ensure();
|
|
159
|
+
const row = sql
|
|
160
|
+
.exec("SELECT payload FROM oyster_website_bindings WHERE site_key=?", siteKey)
|
|
161
|
+
.toArray()[0];
|
|
162
|
+
return row === undefined ? null : decode(payloadRow.parse(row));
|
|
163
|
+
},
|
|
164
|
+
list: () => {
|
|
165
|
+
ensure();
|
|
166
|
+
return sql
|
|
167
|
+
.exec("SELECT payload FROM oyster_website_bindings ORDER BY binding_id")
|
|
168
|
+
.toArray()
|
|
169
|
+
.map((row) => decode(payloadRow.parse(row)));
|
|
170
|
+
},
|
|
171
|
+
/** Create once per request identity; a replay returns the first result. */
|
|
172
|
+
create: (rawInput, requestId) => {
|
|
173
|
+
const parsed = createWebsiteInputSchema.safeParse(rawInput);
|
|
174
|
+
const identity = requestIdSchema.safeParse(requestId);
|
|
175
|
+
if (!parsed.success || !identity.success)
|
|
176
|
+
throw new WebsiteBindingError("invalid_input");
|
|
177
|
+
const input = parsed.data;
|
|
178
|
+
const inputJson = JSON.stringify(input);
|
|
179
|
+
return options.transactionSync(() => {
|
|
180
|
+
ensure();
|
|
181
|
+
const prior = sql
|
|
182
|
+
.exec("SELECT input_json,payload FROM oyster_website_bindings WHERE request_id=?", identity.data)
|
|
183
|
+
.toArray()[0];
|
|
184
|
+
if (prior !== undefined) {
|
|
185
|
+
const receipt = receiptRow.parse(prior);
|
|
186
|
+
if (receipt.input_json !== inputJson)
|
|
187
|
+
throw new WebsiteBindingError("request_conflict");
|
|
188
|
+
return decode(receipt);
|
|
189
|
+
}
|
|
190
|
+
if (!options.agentExists(input.agentId))
|
|
191
|
+
throw new WebsiteBindingError("not_found");
|
|
192
|
+
const binding = websiteBindingSchema.parse({
|
|
193
|
+
bindingId: channelIds.binding.generate(),
|
|
194
|
+
agentId: input.agentId,
|
|
195
|
+
selector: mintWebSelector(input.selector),
|
|
196
|
+
lifecycle: "active",
|
|
197
|
+
authorityVersion: 1,
|
|
198
|
+
persona: input.persona,
|
|
199
|
+
});
|
|
200
|
+
sql.exec("INSERT INTO oyster_website_bindings (binding_id,agent_id,site_key,request_id,input_json,payload) VALUES (?,?,?,?,?,?)", binding.bindingId, binding.agentId, binding.selector.siteKey, identity.data, inputJson, JSON.stringify(binding));
|
|
201
|
+
return binding;
|
|
202
|
+
});
|
|
203
|
+
},
|
|
204
|
+
update: (bindingId, rawInput) => {
|
|
205
|
+
const parsed = updateWebsiteInputSchema.safeParse(rawInput);
|
|
206
|
+
if (!parsed.success)
|
|
207
|
+
throw new WebsiteBindingError("invalid_input");
|
|
208
|
+
const input = parsed.data;
|
|
209
|
+
return options.transactionSync(() => {
|
|
210
|
+
const current = read(bindingId);
|
|
211
|
+
if (current === null)
|
|
212
|
+
throw new WebsiteBindingError("not_found");
|
|
213
|
+
if (current.authorityVersion !== input.expectedVersion)
|
|
214
|
+
throw new WebsiteBindingError("version_conflict");
|
|
215
|
+
const next = websiteBindingSchema.parse({
|
|
216
|
+
...current,
|
|
217
|
+
selector: editWebSelector(current.selector, input),
|
|
218
|
+
lifecycle: input.lifecycle ?? current.lifecycle,
|
|
219
|
+
persona: input.persona ?? current.persona,
|
|
220
|
+
authorityVersion: current.authorityVersion + 1,
|
|
221
|
+
});
|
|
222
|
+
sql.exec("UPDATE oyster_website_bindings SET site_key=?, payload=? WHERE binding_id=?", next.selector.siteKey, JSON.stringify(next), bindingId);
|
|
223
|
+
return next;
|
|
224
|
+
});
|
|
225
|
+
},
|
|
226
|
+
};
|
|
227
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
// Build-time facts about the website visitor programs. Never import this
|
|
2
|
+
// from a Worker: it is megabytes of source every isolate would carry.
|
|
3
|
+
|
|
4
|
+
/** The launcher's real esbuild graph, for consumer asset checks. */
|
|
5
|
+
export declare const embedLoaderMetafile: import("esbuild").Metafile;
|
|
6
|
+
|
|
7
|
+
/** The widget's real esbuild graph, for consumer browser-boundary checks. */
|
|
8
|
+
export declare const embedWidgetMetafile: import("esbuild").Metafile;
|