@familiar-ai/cloudflare 0.1.6 → 0.3.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 +28 -25
- package/dist/alarm.js +3 -4
- package/dist/durable-workspace.d.ts +47 -0
- package/dist/{durable-familiar.js → durable-workspace.js} +46 -50
- package/dist/index.d.ts +1 -3
- package/dist/index.js +1 -3
- package/package.json +7 -4
- package/dist/durable-familiar.d.ts +0 -50
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @familiar-ai/cloudflare
|
|
2
2
|
|
|
3
|
-
Runs one Familiar in one SQLite-backed Cloudflare Durable Object. It owns storage, alarms and recovery after eviction. The [
|
|
3
|
+
Runs one Familiar workspace in one SQLite-backed Cloudflare Durable Object. It owns storage, alarms and recovery after eviction. The [Cloudflare Worker example](../../examples/cloudflare-worker/README.md) hosts it with a scripted model. See [Host on Cloudflare](https://aidanzealley.github.io/familiar/build/cloudflare/) (publishes once GitHub Pages deployment is enabled).
|
|
4
4
|
|
|
5
5
|
```sh
|
|
6
6
|
npm install @familiar-ai/core @familiar-ai/cloudflare
|
|
@@ -10,46 +10,49 @@ Use this package only in Workers. Inside your Durable Object, construct the adap
|
|
|
10
10
|
|
|
11
11
|
```ts
|
|
12
12
|
import { DurableObject } from 'cloudflare:workers'
|
|
13
|
-
import {
|
|
14
|
-
import {
|
|
15
|
-
import {
|
|
16
|
-
fauxProvider,
|
|
17
|
-
fauxAssistantMessage,
|
|
18
|
-
} from '@familiar-ai/core/models/faux'
|
|
13
|
+
import { DurableWorkspace } from '@familiar-ai/cloudflare'
|
|
14
|
+
import { fauxAssistantMessage } from '@familiar-ai/core/models/faux'
|
|
15
|
+
import { scriptedModels } from '@familiar-ai/core/models/scripted'
|
|
19
16
|
|
|
20
17
|
export class Bot extends DurableObject {
|
|
21
|
-
readonly
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
faux
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
18
|
+
readonly workspace = new DurableWorkspace(this.ctx, {
|
|
19
|
+
workspace: () => ({
|
|
20
|
+
models: scriptedModels(() =>
|
|
21
|
+
fauxAssistantMessage('Hello from a Worker.'),
|
|
22
|
+
),
|
|
23
|
+
chatModel: { provider: 'faux', modelId: 'faux-1' },
|
|
24
|
+
timeZone: 'Europe/London',
|
|
25
|
+
}),
|
|
26
|
+
// After each open: make its Familiar the first time.
|
|
27
|
+
setup: async (workspace) => {
|
|
28
|
+
if (!(await workspace.familiars.list()).length) {
|
|
29
|
+
await workspace.familiars.create({ name: 'Bot' })
|
|
31
30
|
}
|
|
32
31
|
},
|
|
33
32
|
})
|
|
34
33
|
|
|
35
34
|
override alarm() {
|
|
36
|
-
return this.
|
|
35
|
+
return this.workspace.alarm()
|
|
37
36
|
}
|
|
38
37
|
|
|
39
38
|
async greet() {
|
|
40
|
-
return this.
|
|
41
|
-
|
|
39
|
+
return this.workspace.use(async (workspace) => {
|
|
40
|
+
const [familiar] = await workspace.familiars.list()
|
|
41
|
+
const dm = await workspace.rooms.get(
|
|
42
|
+
await workspace.rooms.dm(familiar.id, 'owner'),
|
|
43
|
+
)
|
|
44
|
+
return dm!.post({
|
|
42
45
|
author: { id: 'owner', name: 'Sam' },
|
|
43
46
|
text: 'Hello',
|
|
44
47
|
requestId: crypto.randomUUID(),
|
|
45
|
-
})
|
|
46
|
-
)
|
|
48
|
+
})
|
|
49
|
+
})
|
|
47
50
|
}
|
|
48
51
|
}
|
|
49
52
|
```
|
|
50
53
|
|
|
51
|
-
This scripted model
|
|
54
|
+
This scripted model answers every request alike. A lasting host configures its own provider, credentials, notifications, network policy and tools in the factory, and its Familiars and rooms in `setup`. Configure a SQLite Durable Object binding and migration in Wrangler; see the [example's configuration](../../examples/cloudflare-worker/wrangler.jsonc).
|
|
52
55
|
|
|
53
|
-
Reach the
|
|
56
|
+
Reach the workspace through `use()` so recovery is armed before work starts, and don't call its `dismiss()`. `terminate()` permanently refuses that object ID while keeping history.
|
|
54
57
|
|
|
55
|
-
Local workerd tests cover reminder delivery
|
|
58
|
+
Local workerd tests cover reminder delivery, whether the object was evicted or stayed in memory, interrupted-reply recovery and persistent termination. ChatGPT sign-in and real-model operation on Workers have not been verified.
|
package/dist/alarm.js
CHANGED
|
@@ -3,11 +3,10 @@
|
|
|
3
3
|
* later than the earliest sleep; null when nothing needs a process.
|
|
4
4
|
*/
|
|
5
5
|
export function alarmTime(wake, now, heartbeatMs) {
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
return heartbeat ?? wake.at ?? null;
|
|
6
|
+
if (!wake.active) {
|
|
7
|
+
return wake.at ?? null;
|
|
9
8
|
}
|
|
10
|
-
return Math.min(
|
|
9
|
+
return Math.min(now + heartbeatMs, wake.at ?? Infinity);
|
|
11
10
|
}
|
|
12
11
|
/**
|
|
13
12
|
* Writes the object's alarm, or deletes it for null. Writes go through the
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { type Workspace, type WorkspaceOptions } from '@familiar-ai/core';
|
|
2
|
+
/**
|
|
3
|
+
* Everything a host chooses about its workspace: models, zone, plugins,
|
|
4
|
+
* notifications, network and secrets. The adapter owns storage and waking.
|
|
5
|
+
*/
|
|
6
|
+
export type HostWorkspaceOptions = Omit<WorkspaceOptions, 'storage' | 'now' | 'setTimer' | 'onWake'>;
|
|
7
|
+
export type DurableWorkspaceOptions = {
|
|
8
|
+
/** Called each time the object opens its workspace, after a restart or eviction too. */
|
|
9
|
+
workspace: () => HostWorkspaceOptions | Promise<HostWorkspaceOptions>;
|
|
10
|
+
/**
|
|
11
|
+
* Runs after each open, before any request or alarm reaches the
|
|
12
|
+
* workspace, such as to create its Familiars and rooms the first time.
|
|
13
|
+
*/
|
|
14
|
+
setup?: (workspace: Workspace) => Promise<void>;
|
|
15
|
+
/**
|
|
16
|
+
* How soon work a lost process left is resumed: the alarm while anything
|
|
17
|
+
* runs, and the fallback while opening. Default one minute.
|
|
18
|
+
*/
|
|
19
|
+
heartbeatMs?: number;
|
|
20
|
+
};
|
|
21
|
+
/** Refused because the workspace was terminated. Its object ID never opens again. */
|
|
22
|
+
export declare class WorkspaceTerminated extends Error {
|
|
23
|
+
constructor();
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* One workspace in one SQLite-backed Durable Object. Construct it in the
|
|
27
|
+
* object's constructor or a field, route `alarm()` to it, and reach the
|
|
28
|
+
* workspace only through `use()`, which arms recovery before work can start.
|
|
29
|
+
*/
|
|
30
|
+
export declare class DurableWorkspace {
|
|
31
|
+
#private;
|
|
32
|
+
constructor(ctx: DurableObjectState, options: DurableWorkspaceOptions);
|
|
33
|
+
/**
|
|
34
|
+
* Runs `work` with the workspace, after arming a recovery alarm, because
|
|
35
|
+
* any call can start work. Rejects with WorkspaceTerminated once
|
|
36
|
+
* terminated. Leave closing to `terminate()`: don't call `dismiss()`.
|
|
37
|
+
*/
|
|
38
|
+
use<T>(work: (workspace: Workspace) => T | Promise<T>): Promise<T>;
|
|
39
|
+
/** The object's `alarm()`: runs whatever is due or was cut off. */
|
|
40
|
+
alarm(): Promise<void>;
|
|
41
|
+
/**
|
|
42
|
+
* Stops the workspace for good, keeping its history: records that it's
|
|
43
|
+
* terminated and deletes the alarm in one transaction, then closes it,
|
|
44
|
+
* cutting off any reply. Later requests, alarms and restarts are refused.
|
|
45
|
+
*/
|
|
46
|
+
terminate(): Promise<void>;
|
|
47
|
+
}
|
|
@@ -1,26 +1,30 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import { summonFamiliar, } from '@familiar-ai/core';
|
|
1
|
+
import { DurableObjectSqliteDatabase, openDurableObjectSqliteStorage, } from '@earendil-works/pi-durable/storage/sqlite/cloudflare';
|
|
2
|
+
import { openWorkspace, } from '@familiar-ai/core';
|
|
4
3
|
import { alarmTime, alarmWriter } from "./alarm.js";
|
|
5
|
-
/** Refused because the
|
|
6
|
-
export class
|
|
4
|
+
/** Refused because the workspace was terminated. Its object ID never opens again. */
|
|
5
|
+
export class WorkspaceTerminated extends Error {
|
|
7
6
|
constructor() {
|
|
8
|
-
super('This
|
|
9
|
-
this.name = '
|
|
7
|
+
super('This workspace was terminated.');
|
|
8
|
+
this.name = 'WorkspaceTerminated';
|
|
10
9
|
}
|
|
11
10
|
}
|
|
12
11
|
const HEARTBEAT_MS = 60_000;
|
|
13
|
-
/** Pi's tables, apart from the
|
|
12
|
+
/** Pi's tables, apart from any the host keeps in the same object. */
|
|
14
13
|
const PI_PREFIX = 'pi_';
|
|
14
|
+
/** The object's key-value record that it was terminated, and when. */
|
|
15
|
+
const TERMINATED = 'familiar.terminated';
|
|
15
16
|
/**
|
|
16
|
-
* One
|
|
17
|
+
* One workspace in one SQLite-backed Durable Object. Construct it in the
|
|
17
18
|
* object's constructor or a field, route `alarm()` to it, and reach the
|
|
18
|
-
*
|
|
19
|
+
* workspace only through `use()`, which arms recovery before work can start.
|
|
19
20
|
*/
|
|
20
|
-
export class
|
|
21
|
+
export class DurableWorkspace {
|
|
21
22
|
#ctx;
|
|
22
23
|
#heartbeatMs;
|
|
23
|
-
/**
|
|
24
|
+
/**
|
|
25
|
+
* Pi's database on the same storage shares this one's queue, so alarm
|
|
26
|
+
* writes and termination wait for Pi's commits instead of interleaving.
|
|
27
|
+
*/
|
|
24
28
|
#database;
|
|
25
29
|
#writeAlarm;
|
|
26
30
|
#runtime = { status: 'opening' };
|
|
@@ -34,17 +38,17 @@ export class DurableFamiliar {
|
|
|
34
38
|
void ctx.blockConcurrencyWhile(() => this.#open(options));
|
|
35
39
|
}
|
|
36
40
|
/**
|
|
37
|
-
* Runs `work` with the
|
|
38
|
-
* any call can start work. Rejects with
|
|
39
|
-
* Leave closing to `terminate()`: don't call `dismiss()`.
|
|
41
|
+
* Runs `work` with the workspace, after arming a recovery alarm, because
|
|
42
|
+
* any call can start work. Rejects with WorkspaceTerminated once
|
|
43
|
+
* terminated. Leave closing to `terminate()`: don't call `dismiss()`.
|
|
40
44
|
*/
|
|
41
45
|
async use(work) {
|
|
42
46
|
const runtime = this.#runtime;
|
|
43
47
|
if (runtime.status !== 'open') {
|
|
44
|
-
throw new
|
|
48
|
+
throw new WorkspaceTerminated();
|
|
45
49
|
}
|
|
46
|
-
await this.#arm({ ...runtime.
|
|
47
|
-
return work(runtime.
|
|
50
|
+
await this.#arm({ ...runtime.workspace.wake(), active: true });
|
|
51
|
+
return work(runtime.workspace);
|
|
48
52
|
}
|
|
49
53
|
/** The object's `alarm()`: runs whatever is due or was cut off. */
|
|
50
54
|
async alarm() {
|
|
@@ -52,24 +56,25 @@ export class DurableFamiliar {
|
|
|
52
56
|
if (runtime.status !== 'open') {
|
|
53
57
|
return this.#writeAlarm(null);
|
|
54
58
|
}
|
|
55
|
-
await this.#arm({ ...runtime.
|
|
56
|
-
runtime.
|
|
59
|
+
await this.#arm({ ...runtime.workspace.wake(), active: true });
|
|
60
|
+
runtime.workspace.resume();
|
|
57
61
|
// Pi tells onWake only of changes, and the heartbeat above wasn't one.
|
|
58
62
|
// Due work already counts as active here.
|
|
59
|
-
await this.#arm(runtime.
|
|
63
|
+
await this.#arm(runtime.workspace.wake());
|
|
60
64
|
}
|
|
61
65
|
/**
|
|
62
|
-
* Stops the
|
|
63
|
-
* terminated and deletes the alarm in one transaction, then
|
|
64
|
-
*
|
|
66
|
+
* Stops the workspace for good, keeping its history: records that it's
|
|
67
|
+
* terminated and deletes the alarm in one transaction, then closes it,
|
|
68
|
+
* cutting off any reply. Later requests, alarms and restarts are refused.
|
|
65
69
|
*/
|
|
66
70
|
async terminate() {
|
|
67
71
|
const runtime = this.#runtime;
|
|
68
|
-
// Refuses new calls at once
|
|
72
|
+
// Refuses new calls at once, without relying on the object holding
|
|
73
|
+
// requests back during the commit; any late alarm write becomes a delete.
|
|
69
74
|
this.#runtime = { status: 'terminated' };
|
|
70
75
|
try {
|
|
71
|
-
await this.#database.transaction(async (
|
|
72
|
-
|
|
76
|
+
await this.#database.transaction(async () => {
|
|
77
|
+
this.#ctx.storage.kv.put(TERMINATED, Date.now());
|
|
73
78
|
await this.#ctx.storage.deleteAlarm();
|
|
74
79
|
});
|
|
75
80
|
}
|
|
@@ -79,26 +84,13 @@ export class DurableFamiliar {
|
|
|
79
84
|
throw error;
|
|
80
85
|
}
|
|
81
86
|
if (runtime.status === 'open') {
|
|
82
|
-
|
|
83
|
-
await runtime.familiar.abort();
|
|
84
|
-
}
|
|
85
|
-
finally {
|
|
86
|
-
await runtime.familiar.dismiss();
|
|
87
|
-
}
|
|
87
|
+
await runtime.workspace.dismiss();
|
|
88
88
|
}
|
|
89
89
|
}
|
|
90
|
-
async status() {
|
|
91
|
-
const runtime = this.#runtime;
|
|
92
|
-
const alarm = await this.#ctx.storage.getAlarm();
|
|
93
|
-
return runtime.status === 'open'
|
|
94
|
-
? { status: 'open', alarm, wake: runtime.familiar.wake() }
|
|
95
|
-
: { status: 'terminated', alarm };
|
|
96
|
-
}
|
|
97
90
|
async #open(options) {
|
|
98
|
-
|
|
99
|
-
if (
|
|
91
|
+
// A stray alarm left behind is deleted by alarm() when it fires.
|
|
92
|
+
if (this.#ctx.storage.kv.get(TERMINATED) !== undefined) {
|
|
100
93
|
this.#runtime = { status: 'terminated' };
|
|
101
|
-
await this.#writeAlarm(null);
|
|
102
94
|
return;
|
|
103
95
|
}
|
|
104
96
|
// Armed before anything can run or throw, and kept until open.
|
|
@@ -107,19 +99,23 @@ export class DurableFamiliar {
|
|
|
107
99
|
if (current === null || current > fallback) {
|
|
108
100
|
await this.#writeAlarm(fallback);
|
|
109
101
|
}
|
|
110
|
-
const
|
|
111
|
-
...(await options.
|
|
112
|
-
storage: await
|
|
102
|
+
const workspace = await openWorkspace({
|
|
103
|
+
...(await options.workspace()),
|
|
104
|
+
storage: await openDurableObjectSqliteStorage(this.#ctx.storage, {
|
|
105
|
+
prefix: PI_PREFIX,
|
|
106
|
+
}),
|
|
113
107
|
onWake: (wake) => void this.#arm(wake).catch(() => { }),
|
|
114
108
|
});
|
|
115
|
-
void
|
|
109
|
+
void workspace.closed.then((end) => {
|
|
116
110
|
if (end.reason === 'failed' && this.#runtime.status !== 'terminated') {
|
|
117
111
|
// Keep the recovery alarm: the next instance reopens persisted work.
|
|
118
|
-
this.#ctx.abort('
|
|
112
|
+
this.#ctx.abort('Workspace storage failed');
|
|
119
113
|
}
|
|
120
114
|
});
|
|
121
|
-
|
|
122
|
-
await
|
|
115
|
+
// Still under the fallback alarm: if setup throws, the object resets.
|
|
116
|
+
await options.setup?.(workspace);
|
|
117
|
+
this.#runtime = { status: 'open', workspace };
|
|
118
|
+
await this.#arm(workspace.wake());
|
|
123
119
|
}
|
|
124
120
|
/** Writes the alarm `wake` asks for, as the runtime allows. */
|
|
125
121
|
#arm(wake) {
|
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1 @@
|
|
|
1
|
-
export {
|
|
2
|
-
export { openDurableObjectSqliteStorage, DurableObjectSqliteDatabase, } from '@earendil-works/pi-durable/storage/sqlite/cloudflare';
|
|
3
|
-
export { SqliteStorage, type SqliteStorageOptions, } from '@earendil-works/pi-durable/storage/sqlite';
|
|
1
|
+
export { DurableWorkspace, WorkspaceTerminated, type DurableWorkspaceOptions, type HostWorkspaceOptions, } from './durable-workspace.ts';
|
package/dist/index.js
CHANGED
|
@@ -1,3 +1 @@
|
|
|
1
|
-
export {
|
|
2
|
-
export { openDurableObjectSqliteStorage, DurableObjectSqliteDatabase, } from '@earendil-works/pi-durable/storage/sqlite/cloudflare';
|
|
3
|
-
export { SqliteStorage, } from '@earendil-works/pi-durable/storage/sqlite';
|
|
1
|
+
export { DurableWorkspace, WorkspaceTerminated, } from "./durable-workspace.js";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@familiar-ai/cloudflare",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -18,17 +18,20 @@
|
|
|
18
18
|
"access": "public"
|
|
19
19
|
},
|
|
20
20
|
"peerDependencies": {
|
|
21
|
-
"@familiar-ai/core": "0.
|
|
21
|
+
"@familiar-ai/core": "0.3.0"
|
|
22
22
|
},
|
|
23
23
|
"devDependencies": {
|
|
24
24
|
"@cloudflare/workers-types": "5.20261023.1",
|
|
25
|
-
"
|
|
25
|
+
"vitest": "^5.0.5",
|
|
26
|
+
"wrangler": "4.156.0",
|
|
27
|
+
"@familiar-ai/core": "0.3.0"
|
|
26
28
|
},
|
|
27
29
|
"dependencies": {
|
|
28
30
|
"@earendil-works/pi-durable": "1.4.0"
|
|
29
31
|
},
|
|
30
32
|
"scripts": {
|
|
31
33
|
"typecheck": "tsc",
|
|
32
|
-
"build": "tsc -p tsconfig.build.json"
|
|
34
|
+
"build": "tsc -p tsconfig.build.json",
|
|
35
|
+
"test": "vitest run"
|
|
33
36
|
}
|
|
34
37
|
}
|
|
@@ -1,50 +0,0 @@
|
|
|
1
|
-
import { type Familiar, type FamiliarOptions, type Wake } from '@familiar-ai/core';
|
|
2
|
-
/**
|
|
3
|
-
* Everything a host chooses about its Familiar: models, zone, plugins,
|
|
4
|
-
* notifications, network and secrets. The adapter owns storage and waking.
|
|
5
|
-
*/
|
|
6
|
-
export type HostFamiliarOptions = Omit<FamiliarOptions, 'storage' | 'now' | 'setTimer' | 'onWake'>;
|
|
7
|
-
export type DurableFamiliarOptions = {
|
|
8
|
-
/** Called each time the object opens its Familiar, after a restart or eviction too. */
|
|
9
|
-
familiar: () => HostFamiliarOptions | Promise<HostFamiliarOptions>;
|
|
10
|
-
/**
|
|
11
|
-
* How soon work a lost process left is resumed: the alarm while anything
|
|
12
|
-
* runs, and the fallback while opening. Default one minute.
|
|
13
|
-
*/
|
|
14
|
-
heartbeatMs?: number;
|
|
15
|
-
};
|
|
16
|
-
export type DurableFamiliarStatus = {
|
|
17
|
-
status: 'open' | 'terminated';
|
|
18
|
-
/** The armed alarm, epoch milliseconds. */
|
|
19
|
-
alarm: number | null;
|
|
20
|
-
/** What the Familiar says it needs; absent once terminated. */
|
|
21
|
-
wake?: Wake;
|
|
22
|
-
};
|
|
23
|
-
/** Refused because the Familiar was terminated. Its ID never opens again. */
|
|
24
|
-
export declare class FamiliarTerminated extends Error {
|
|
25
|
-
constructor();
|
|
26
|
-
}
|
|
27
|
-
/**
|
|
28
|
-
* One Familiar in one SQLite-backed Durable Object. Construct it in the
|
|
29
|
-
* object's constructor or a field, route `alarm()` to it, and reach the
|
|
30
|
-
* Familiar only through `use()`, which arms recovery before work can start.
|
|
31
|
-
*/
|
|
32
|
-
export declare class DurableFamiliar {
|
|
33
|
-
#private;
|
|
34
|
-
constructor(ctx: DurableObjectState, options: DurableFamiliarOptions);
|
|
35
|
-
/**
|
|
36
|
-
* Runs `work` with the Familiar, after arming a recovery alarm, because
|
|
37
|
-
* any call can start work. Rejects with FamiliarTerminated once terminated.
|
|
38
|
-
* Leave closing to `terminate()`: don't call `dismiss()`.
|
|
39
|
-
*/
|
|
40
|
-
use<T>(work: (familiar: Familiar) => T | Promise<T>): Promise<T>;
|
|
41
|
-
/** The object's `alarm()`: runs whatever is due or was cut off. */
|
|
42
|
-
alarm(): Promise<void>;
|
|
43
|
-
/**
|
|
44
|
-
* Stops the Familiar for good, keeping its history: records that it's
|
|
45
|
-
* terminated and deletes the alarm in one transaction, then stops the
|
|
46
|
-
* current run and closes. Later requests, alarms and restarts are refused.
|
|
47
|
-
*/
|
|
48
|
-
terminate(): Promise<void>;
|
|
49
|
-
status(): Promise<DurableFamiliarStatus>;
|
|
50
|
-
}
|