@familiar-ai/cloudflare 0.1.5 → 0.2.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 +48 -0
- package/dist/alarm.js +3 -4
- package/dist/durable-familiar.d.ts +1 -9
- package/dist/durable-familiar.js +17 -18
- package/dist/index.d.ts +1 -1
- package/package.json +10 -6
package/README.md
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# @familiar-ai/cloudflare
|
|
2
|
+
|
|
3
|
+
Runs one Familiar 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
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm install @familiar-ai/core @familiar-ai/cloudflare
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Use this package only in Workers. Inside your Durable Object, construct the adapter and forward its alarm:
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { DurableObject } from 'cloudflare:workers'
|
|
13
|
+
import { DurableFamiliar } from '@familiar-ai/cloudflare'
|
|
14
|
+
import { fauxAssistantMessage } from '@familiar-ai/core/models/faux'
|
|
15
|
+
import { scriptedModels } from '@familiar-ai/core/models/scripted'
|
|
16
|
+
|
|
17
|
+
export class Bot extends DurableObject {
|
|
18
|
+
readonly familiar = new DurableFamiliar(this.ctx, {
|
|
19
|
+
familiar: () => ({
|
|
20
|
+
models: scriptedModels(() =>
|
|
21
|
+
fauxAssistantMessage('Hello from a Worker.'),
|
|
22
|
+
),
|
|
23
|
+
model: { provider: 'faux', modelId: 'faux-1' },
|
|
24
|
+
timeZone: 'Europe/London',
|
|
25
|
+
}),
|
|
26
|
+
})
|
|
27
|
+
|
|
28
|
+
override alarm() {
|
|
29
|
+
return this.familiar.alarm()
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
async greet() {
|
|
33
|
+
return this.familiar.use((familiar) =>
|
|
34
|
+
familiar.send({
|
|
35
|
+
author: { id: 'owner', name: 'Sam' },
|
|
36
|
+
text: 'Hello',
|
|
37
|
+
requestId: crypto.randomUUID(),
|
|
38
|
+
}),
|
|
39
|
+
)
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
This scripted model answers every request alike. A lasting host configures its own provider, credentials, notifications, network policy and tools in the factory. Configure a SQLite Durable Object binding and migration in Wrangler; see the [example's configuration](../../examples/cloudflare-worker/wrangler.jsonc).
|
|
45
|
+
|
|
46
|
+
Reach the assistant through `use()` so recovery is armed before work starts, and don't call its `dismiss()`. `terminate()` permanently refuses that object ID while keeping history.
|
|
47
|
+
|
|
48
|
+
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
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type Familiar, type FamiliarOptions
|
|
1
|
+
import { type Familiar, type FamiliarOptions } from '@familiar-ai/core';
|
|
2
2
|
/**
|
|
3
3
|
* Everything a host chooses about its Familiar: models, zone, plugins,
|
|
4
4
|
* notifications, network and secrets. The adapter owns storage and waking.
|
|
@@ -13,13 +13,6 @@ export type DurableFamiliarOptions = {
|
|
|
13
13
|
*/
|
|
14
14
|
heartbeatMs?: number;
|
|
15
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
16
|
/** Refused because the Familiar was terminated. Its ID never opens again. */
|
|
24
17
|
export declare class FamiliarTerminated extends Error {
|
|
25
18
|
constructor();
|
|
@@ -46,5 +39,4 @@ export declare class DurableFamiliar {
|
|
|
46
39
|
* current run and closes. Later requests, alarms and restarts are refused.
|
|
47
40
|
*/
|
|
48
41
|
terminate(): Promise<void>;
|
|
49
|
-
status(): Promise<DurableFamiliarStatus>;
|
|
50
42
|
}
|
package/dist/durable-familiar.js
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { DurableObjectSqliteDatabase } from '@earendil-works/pi-durable/storage/sqlite/cloudflare';
|
|
1
|
+
import { DurableObjectSqliteDatabase, openDurableObjectSqliteStorage, } from '@earendil-works/pi-durable/storage/sqlite/cloudflare';
|
|
3
2
|
import { summonFamiliar, } from '@familiar-ai/core';
|
|
4
3
|
import { alarmTime, alarmWriter } from "./alarm.js";
|
|
5
4
|
/** Refused because the Familiar was terminated. Its ID never opens again. */
|
|
@@ -10,8 +9,10 @@ export class FamiliarTerminated extends Error {
|
|
|
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
17
|
* One Familiar 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
|
|
@@ -20,7 +21,10 @@ const PI_PREFIX = 'pi_';
|
|
|
20
21
|
export class DurableFamiliar {
|
|
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' };
|
|
@@ -65,11 +69,12 @@ export class DurableFamiliar {
|
|
|
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
|
}
|
|
@@ -87,18 +92,10 @@ export class DurableFamiliar {
|
|
|
87
92
|
}
|
|
88
93
|
}
|
|
89
94
|
}
|
|
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
95
|
async #open(options) {
|
|
98
|
-
|
|
99
|
-
if (
|
|
96
|
+
// A stray alarm left behind is deleted by alarm() when it fires.
|
|
97
|
+
if (this.#ctx.storage.kv.get(TERMINATED) !== undefined) {
|
|
100
98
|
this.#runtime = { status: 'terminated' };
|
|
101
|
-
await this.#writeAlarm(null);
|
|
102
99
|
return;
|
|
103
100
|
}
|
|
104
101
|
// Armed before anything can run or throw, and kept until open.
|
|
@@ -109,7 +106,9 @@ export class DurableFamiliar {
|
|
|
109
106
|
}
|
|
110
107
|
const familiar = await summonFamiliar({
|
|
111
108
|
...(await options.familiar()),
|
|
112
|
-
storage: await
|
|
109
|
+
storage: await openDurableObjectSqliteStorage(this.#ctx.storage, {
|
|
110
|
+
prefix: PI_PREFIX,
|
|
111
|
+
}),
|
|
113
112
|
onWake: (wake) => void this.#arm(wake).catch(() => { }),
|
|
114
113
|
});
|
|
115
114
|
void familiar.closed.then((end) => {
|
package/dist/index.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export { DurableFamiliar, FamiliarTerminated, type DurableFamiliarOptions, type
|
|
1
|
+
export { DurableFamiliar, FamiliarTerminated, type DurableFamiliarOptions, type HostFamiliarOptions, } from './durable-familiar.ts';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@familiar-ai/cloudflare",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -18,16 +18,20 @@
|
|
|
18
18
|
"access": "public"
|
|
19
19
|
},
|
|
20
20
|
"peerDependencies": {
|
|
21
|
-
"@
|
|
22
|
-
"@familiar-ai/core": "0.1.5"
|
|
21
|
+
"@familiar-ai/core": "0.2.0"
|
|
23
22
|
},
|
|
24
23
|
"devDependencies": {
|
|
25
24
|
"@cloudflare/workers-types": "5.20261023.1",
|
|
26
|
-
"
|
|
27
|
-
"
|
|
25
|
+
"vitest": "^5.0.5",
|
|
26
|
+
"wrangler": "4.156.0",
|
|
27
|
+
"@familiar-ai/core": "0.2.0"
|
|
28
|
+
},
|
|
29
|
+
"dependencies": {
|
|
30
|
+
"@earendil-works/pi-durable": "1.4.0"
|
|
28
31
|
},
|
|
29
32
|
"scripts": {
|
|
30
33
|
"typecheck": "tsc",
|
|
31
|
-
"build": "tsc -p tsconfig.build.json"
|
|
34
|
+
"build": "tsc -p tsconfig.build.json",
|
|
35
|
+
"test": "vitest run"
|
|
32
36
|
}
|
|
33
37
|
}
|