@familiar-ai/cloudflare 0.0.0-stage → 0.0.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/LICENSE +21 -0
- package/dist/alarm.d.ts +14 -0
- package/dist/alarm.js +25 -0
- package/dist/durable-familiar.d.ts +50 -0
- package/dist/durable-familiar.js +135 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/package.json +30 -3
- package/README.md +0 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aidan Zealley
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/dist/alarm.d.ts
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { Wake } from '@familiar-ai/core';
|
|
2
|
+
import type { DurableObjectSqliteDatabase } from '@earendil-works/pi-durable/storage/sqlite/cloudflare';
|
|
3
|
+
/**
|
|
4
|
+
* When to wake for `wake`: a recovery heartbeat while work can run, never
|
|
5
|
+
* later than the earliest sleep; null when nothing needs a process.
|
|
6
|
+
*/
|
|
7
|
+
export declare function alarmTime(wake: Wake, now: number, heartbeatMs: number): number | null;
|
|
8
|
+
/**
|
|
9
|
+
* Writes the object's alarm, or deletes it for null. Writes go through the
|
|
10
|
+
* database queue Pi's commits use, so they land in the order asked and a
|
|
11
|
+
* rolled-back Pi transaction can't take one with it. A failed write resets
|
|
12
|
+
* the object, which arms again when it next starts.
|
|
13
|
+
*/
|
|
14
|
+
export declare function alarmWriter(ctx: DurableObjectState, database: DurableObjectSqliteDatabase): (at: number | null) => Promise<void>;
|
package/dist/alarm.js
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* When to wake for `wake`: a recovery heartbeat while work can run, never
|
|
3
|
+
* later than the earliest sleep; null when nothing needs a process.
|
|
4
|
+
*/
|
|
5
|
+
export function alarmTime(wake, now, heartbeatMs) {
|
|
6
|
+
const heartbeat = wake.active ? now + heartbeatMs : undefined;
|
|
7
|
+
if (heartbeat === undefined || wake.at === undefined) {
|
|
8
|
+
return heartbeat ?? wake.at ?? null;
|
|
9
|
+
}
|
|
10
|
+
return Math.min(heartbeat, wake.at);
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Writes the object's alarm, or deletes it for null. Writes go through the
|
|
14
|
+
* database queue Pi's commits use, so they land in the order asked and a
|
|
15
|
+
* rolled-back Pi transaction can't take one with it. A failed write resets
|
|
16
|
+
* the object, which arms again when it next starts.
|
|
17
|
+
*/
|
|
18
|
+
export function alarmWriter(ctx, database) {
|
|
19
|
+
return (at) => database
|
|
20
|
+
.transaction(() => at === null ? ctx.storage.deleteAlarm() : ctx.storage.setAlarm(at))
|
|
21
|
+
.catch((error) => {
|
|
22
|
+
ctx.abort('Alarm write failed');
|
|
23
|
+
throw error;
|
|
24
|
+
});
|
|
25
|
+
}
|
|
@@ -0,0 +1,50 @@
|
|
|
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
|
+
}
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
import { SqliteStorage } from '@earendil-works/pi-durable/storage/sqlite';
|
|
2
|
+
import { DurableObjectSqliteDatabase } from '@earendil-works/pi-durable/storage/sqlite/cloudflare';
|
|
3
|
+
import { summonFamiliar, } from '@familiar-ai/core';
|
|
4
|
+
import { alarmTime, alarmWriter } from "./alarm.js";
|
|
5
|
+
/** Refused because the Familiar was terminated. Its ID never opens again. */
|
|
6
|
+
export class FamiliarTerminated extends Error {
|
|
7
|
+
constructor() {
|
|
8
|
+
super('This Familiar was terminated.');
|
|
9
|
+
this.name = 'FamiliarTerminated';
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
const HEARTBEAT_MS = 60_000;
|
|
13
|
+
/** Pi's tables, apart from the adapter's own. */
|
|
14
|
+
const PI_PREFIX = 'pi_';
|
|
15
|
+
/**
|
|
16
|
+
* One Familiar in one SQLite-backed Durable Object. Construct it in the
|
|
17
|
+
* object's constructor or a field, route `alarm()` to it, and reach the
|
|
18
|
+
* Familiar only through `use()`, which arms recovery before work can start.
|
|
19
|
+
*/
|
|
20
|
+
export class DurableFamiliar {
|
|
21
|
+
#ctx;
|
|
22
|
+
#heartbeatMs;
|
|
23
|
+
/** Shared with Pi, so its transactions and the adapter's queries never interleave. */
|
|
24
|
+
#database;
|
|
25
|
+
#writeAlarm;
|
|
26
|
+
#runtime = { status: 'opening' };
|
|
27
|
+
constructor(ctx, options) {
|
|
28
|
+
this.#ctx = ctx;
|
|
29
|
+
this.#heartbeatMs = options.heartbeatMs ?? HEARTBEAT_MS;
|
|
30
|
+
this.#database = new DurableObjectSqliteDatabase(ctx.storage);
|
|
31
|
+
this.#writeAlarm = alarmWriter(ctx, this.#database);
|
|
32
|
+
// No request or alarm arrives until this settles. If it throws, the
|
|
33
|
+
// object resets and the fallback alarm starts it again.
|
|
34
|
+
void ctx.blockConcurrencyWhile(() => this.#open(options));
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Runs `work` with the Familiar, after arming a recovery alarm, because
|
|
38
|
+
* any call can start work. Rejects with FamiliarTerminated once terminated.
|
|
39
|
+
* Leave closing to `terminate()`: don't call `dismiss()`.
|
|
40
|
+
*/
|
|
41
|
+
async use(work) {
|
|
42
|
+
const runtime = this.#runtime;
|
|
43
|
+
if (runtime.status !== 'open') {
|
|
44
|
+
throw new FamiliarTerminated();
|
|
45
|
+
}
|
|
46
|
+
await this.#arm({ ...runtime.familiar.wake(), active: true });
|
|
47
|
+
return work(runtime.familiar);
|
|
48
|
+
}
|
|
49
|
+
/** The object's `alarm()`: runs whatever is due or was cut off. */
|
|
50
|
+
async alarm() {
|
|
51
|
+
const runtime = this.#runtime;
|
|
52
|
+
if (runtime.status !== 'open') {
|
|
53
|
+
return this.#writeAlarm(null);
|
|
54
|
+
}
|
|
55
|
+
await this.#arm({ ...runtime.familiar.wake(), active: true });
|
|
56
|
+
runtime.familiar.resume();
|
|
57
|
+
// Pi tells onWake only of changes, and the heartbeat above wasn't one.
|
|
58
|
+
// Due work already counts as active here.
|
|
59
|
+
await this.#arm(runtime.familiar.wake());
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Stops the Familiar for good, keeping its history: records that it's
|
|
63
|
+
* terminated and deletes the alarm in one transaction, then stops the
|
|
64
|
+
* current run and closes. Later requests, alarms and restarts are refused.
|
|
65
|
+
*/
|
|
66
|
+
async terminate() {
|
|
67
|
+
const runtime = this.#runtime;
|
|
68
|
+
// Refuses new calls at once; any late alarm write becomes a delete.
|
|
69
|
+
this.#runtime = { status: 'terminated' };
|
|
70
|
+
try {
|
|
71
|
+
await this.#database.transaction(async (transaction) => {
|
|
72
|
+
await transaction.run('INSERT INTO familiar_terminated (at) SELECT ? WHERE NOT EXISTS (SELECT 1 FROM familiar_terminated)', Date.now());
|
|
73
|
+
await this.#ctx.storage.deleteAlarm();
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
catch (error) {
|
|
77
|
+
// Memory says terminated but storage doesn't: start again from storage.
|
|
78
|
+
this.#ctx.abort('Termination failed');
|
|
79
|
+
throw error;
|
|
80
|
+
}
|
|
81
|
+
if (runtime.status === 'open') {
|
|
82
|
+
try {
|
|
83
|
+
await runtime.familiar.abort();
|
|
84
|
+
}
|
|
85
|
+
finally {
|
|
86
|
+
await runtime.familiar.dismiss();
|
|
87
|
+
}
|
|
88
|
+
}
|
|
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
|
+
async #open(options) {
|
|
98
|
+
await this.#database.exec('CREATE TABLE IF NOT EXISTS familiar_terminated (at INTEGER NOT NULL)');
|
|
99
|
+
if (await this.#database.get('SELECT at FROM familiar_terminated')) {
|
|
100
|
+
this.#runtime = { status: 'terminated' };
|
|
101
|
+
await this.#writeAlarm(null);
|
|
102
|
+
return;
|
|
103
|
+
}
|
|
104
|
+
// Armed before anything can run or throw, and kept until open.
|
|
105
|
+
const fallback = Date.now() + this.#heartbeatMs;
|
|
106
|
+
const current = await this.#ctx.storage.getAlarm();
|
|
107
|
+
if (current === null || current > fallback) {
|
|
108
|
+
await this.#writeAlarm(fallback);
|
|
109
|
+
}
|
|
110
|
+
const familiar = await summonFamiliar({
|
|
111
|
+
...(await options.familiar()),
|
|
112
|
+
storage: await SqliteStorage.open(this.#database, { prefix: PI_PREFIX }),
|
|
113
|
+
onWake: (wake) => void this.#arm(wake).catch(() => { }),
|
|
114
|
+
});
|
|
115
|
+
void familiar.closed.then((end) => {
|
|
116
|
+
if (end.reason === 'failed' && this.#runtime.status !== 'terminated') {
|
|
117
|
+
// Keep the recovery alarm: the next instance reopens persisted work.
|
|
118
|
+
this.#ctx.abort('Familiar storage failed');
|
|
119
|
+
}
|
|
120
|
+
});
|
|
121
|
+
this.#runtime = { status: 'open', familiar };
|
|
122
|
+
await this.#arm(familiar.wake());
|
|
123
|
+
}
|
|
124
|
+
/** Writes the alarm `wake` asks for, as the runtime allows. */
|
|
125
|
+
#arm(wake) {
|
|
126
|
+
switch (this.#runtime.status) {
|
|
127
|
+
case 'opening':
|
|
128
|
+
return Promise.resolve();
|
|
129
|
+
case 'terminated':
|
|
130
|
+
return this.#writeAlarm(null);
|
|
131
|
+
case 'open':
|
|
132
|
+
return this.#writeAlarm(alarmTime(wake, Date.now(), this.#heartbeatMs));
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { DurableFamiliar, FamiliarTerminated, type DurableFamiliarOptions, type DurableFamiliarStatus, type HostFamiliarOptions, } from './durable-familiar.ts';
|
package/dist/index.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { DurableFamiliar, FamiliarTerminated, } from "./durable-familiar.js";
|
package/package.json
CHANGED
|
@@ -1,6 +1,33 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@familiar-ai/cloudflare",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/AidanZealley/familiar.git",
|
|
9
|
+
"directory": "packages/cloudflare"
|
|
10
|
+
},
|
|
11
|
+
"exports": {
|
|
12
|
+
".": "./dist/index.js"
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"dist"
|
|
16
|
+
],
|
|
17
|
+
"publishConfig": {
|
|
18
|
+
"access": "public"
|
|
19
|
+
},
|
|
20
|
+
"peerDependencies": {
|
|
21
|
+
"@earendil-works/pi-durable": "1.4.0",
|
|
22
|
+
"@familiar-ai/core": "0.0.0"
|
|
23
|
+
},
|
|
24
|
+
"devDependencies": {
|
|
25
|
+
"@cloudflare/workers-types": "5.20261023.1",
|
|
26
|
+
"@earendil-works/pi-durable": "1.4.0",
|
|
27
|
+
"@familiar-ai/core": "0.0.0"
|
|
28
|
+
},
|
|
29
|
+
"scripts": {
|
|
30
|
+
"typecheck": "tsc",
|
|
31
|
+
"build": "tsc -p tsconfig.build.json"
|
|
32
|
+
}
|
|
6
33
|
}
|
package/README.md
DELETED