clavarium-docket 0.1.0-next.1 → 0.1.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 CHANGED
@@ -30,6 +30,6 @@ business. See [docs/protocol.md](docs/protocol.md).
30
30
 
31
31
  No dependency; Node 22 or later.
32
32
 
33
- **Status:** first version (0.1), tested here; not tried with a real agent yet.
33
+ **Status:** first version (0.1), tried with a real coding agent in Clavarium: a reminder it set itself woke it on time, and it said it done.
34
34
 
35
35
  License: MIT.
package/docs/protocol.md CHANGED
@@ -12,8 +12,9 @@ a library for the application that posts events.
12
12
  | `acks.jsonl` | the worker | what it did of each event: done, or failed and why |
13
13
  | `plans.jsonl` | the worker | the reminders it set itself, and those it took back |
14
14
  | `plans-off.jsonl` | the application | the reminders the person took back |
15
+ | `zone` | the application | the person's time zone, one IANA name (optional) |
15
16
 
16
- Every file only grows: nothing is edited, nothing is deleted. Each has one
17
+ Every `.jsonl` file only grows: nothing is edited, nothing is deleted. Each has one
17
18
  writer. There is no address, no port and no key: whoever can read and write
18
19
  the folder is a side.
19
20
 
@@ -60,8 +61,9 @@ command: 0 done, 1 refused, 2 no folder, 64 not understood.
60
61
 
61
62
  ## Time
62
63
 
63
- A folder's time zone is `$DOCKET_TZ` (an IANA name, `Europe/Paris`), else the
64
- machine's. It is written into each plan, so that a cron line keeps meaning
64
+ A folder's time zone is `$DOCKET_TZ` (an IANA name, `Europe/Paris`), else
65
+ the one the application wrote in its `zone` file (`zone(tz)`: the person's,
66
+ since a machine often runs in UTC), else the machine's. It is written into each plan, so that a cron line keeps meaning
65
67
  what it meant where it was set.
66
68
 
67
69
  ## Reminders become events
@@ -81,6 +83,7 @@ was due.
81
83
  | `read()` | `events` (each with `state`: `waiting`, `done` or `failed`, and its `ack`), `plans` (each with `next`, or `off`), `waiting` (how many) |
82
84
  | `tick(now?)` | the events it posted |
83
85
  | `cancel(plan)` | the plan taken back, by the person |
86
+ | `zone(tz)` | the folder's time zone written |
84
87
  | `listen({every})` | events of its own: `acked` (`{event, ack}`), `planned` (`{plan}`), `cancelled` (`{plan}`) |
85
88
 
86
89
  `WAKE` is one line the application may type to a worker that waits at a
@@ -14,10 +14,11 @@
14
14
  * WHAT IS READ HERE WAS WRITTEN BY A WORKER: its notes and its reminders are
15
15
  * text chosen by a program, bounded and cleaned, handed over as text.
16
16
  */
17
- import { appendFileSync, mkdirSync, statSync, lstatSync } from 'node:fs';
17
+ import { appendFileSync, mkdirSync, statSync, lstatSync, writeFileSync, renameSync } from 'node:fs';
18
18
  import { join } from 'node:path';
19
19
  import { randomUUID } from 'node:crypto';
20
20
  import { state, tick, oneLine, TEXT_MAX, DATA_MAX, WAKE, VERSION, FOLDER } from '../server/docket.mjs';
21
+ import { isZone } from '../server/time.mjs';
21
22
 
22
23
  export { WAKE, VERSION, FOLDER };
23
24
 
@@ -46,6 +47,14 @@ export class Docket {
46
47
  /* The reminders that came due, posted as events: once each time each is due. */
47
48
  tick(now = this.#now()) { return tick(this.#dir, { now }); }
48
49
 
50
+ /* The person's time zone (an IANA name), written for the worker: the times it gives are read in it. */
51
+ zone(tz) {
52
+ if (!isZone(tz)) throw new RangeError('Not a time zone.');
53
+ mkdirSync(this.#dir, { recursive: true });
54
+ writeFileSync(join(this.#dir, 'zone.new'), `${tz}\n`);
55
+ renameSync(join(this.#dir, 'zone.new'), join(this.#dir, 'zone'));
56
+ }
57
+
49
58
  /* The person takes a reminder back. */
50
59
  cancel(plan) {
51
60
  const found = this.read().plans.find((p) => p.id === plan);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "clavarium-docket",
3
- "version": "0.1.0-next.1",
3
+ "version": "0.1.0",
4
4
  "description": "Clavarium Docket: events an AI agent or a script sees and acknowledges, and reminders it sets itself (a command and an MCP server, and a library for the application). No dependency.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/clavarium/clavarium-docket#readme",
package/server/docket.mjs CHANGED
@@ -25,7 +25,7 @@ import { randomUUID, createHash } from 'node:crypto';
25
25
  import { createInterface } from 'node:readline';
26
26
  import { zoneOf, isZone, parseWhen, parseIn, parseCron, nextCron, lastCron, wall } from './time.mjs';
27
27
 
28
- export const VERSION = '0.1.0-next.1';
28
+ export const VERSION = '0.1.0';
29
29
  export const FOLDER = '.docket';
30
30
  export const TEXT_MAX = 500;
31
31
  export const NOTE_MAX = 1000;
@@ -115,7 +115,7 @@ export function verbs(dir, { env = process.env, now = () => Date.now() } = {}) {
115
115
  if (waiting.length === 0) said.push('Nothing waits.');
116
116
  else {
117
117
  said.push(`Waiting (${waiting.length}), oldest first; say what you did of each: docket done ID, or docket failed ID "why".`);
118
- const tz = zoneOf(env);
118
+ const tz = zoneOf(env, dir);
119
119
  const when = (e) => (Number.isFinite(Date.parse(e.at)) ? stamp(Date.parse(e.at), tz).replace(/ \(.*\)$/, '') : '?');
120
120
  for (const e of waiting.slice(0, LISTED_MAX)) said.push(` [${e.id.slice(0, ID_SHOWN)}] ${when(e)} ${e.from}/${e.kind}${e.late ? ' (late)' : ''}: ${e.text}${e.data ? `\n data: ${JSON.stringify(e.data).slice(0, 500)}` : ''}`);
121
121
  if (waiting.length > LISTED_MAX) said.push(` ... and ${waiting.length - LISTED_MAX} more`);
@@ -140,7 +140,7 @@ export function verbs(dir, { env = process.env, now = () => Date.now() } = {}) {
140
140
  if (given !== 1) throw new Error('give one of: --at "2026-10-23 09:00", --in 2h, --cron "0 9 * * 1"');
141
141
  const s = state(dir, { now: now() });
142
142
  if (s.plans.filter((p) => !p.off && p.next !== null).length >= PLANS_MAX) throw new Error(`${PLANS_MAX} reminders at most: take one back first`);
143
- const tz = zoneOf(env);
143
+ const tz = zoneOf(env, dir);
144
144
  if (cron) {
145
145
  const c = parseCron(cron);
146
146
  if (!c) throw new Error('a cron line is five fields: minute hour day month weekday ("0 9 * * 1": Mondays at 9:00)');
package/server/time.mjs CHANGED
@@ -1,11 +1,21 @@
1
+ import { lstatSync, readFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+
1
4
  /* TIME, for reminders: a wall-clock time in a time zone, a cron line, and when
2
5
  * it is next due. No dependency: the time zones are the platform's (Intl).
3
6
  */
4
7
 
5
- /* The time zone a folder works in: $DOCKET_TZ, else the machine's. */
6
- export function zoneOf(env = process.env) {
8
+ /* The time zone a folder works in: $DOCKET_TZ, else what the application wrote in its `zone` file
9
+ (the person's: a machine often runs in UTC), else the machine's. */
10
+ export function zoneOf(env = process.env, dir) {
7
11
  const given = String(env.DOCKET_TZ ?? '').trim();
8
12
  if (given && isZone(given)) return given;
13
+ if (dir) {
14
+ try {
15
+ const file = join(dir, 'zone');
16
+ if (lstatSync(file).isFile() && lstatSync(file).size <= 64) { const written = readFileSync(file, 'utf8').trim(); if (isZone(written)) return written; }
17
+ } catch { /* none written */ }
18
+ }
9
19
  try { return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'; } catch { return 'UTC'; }
10
20
  }
11
21
  export function isZone(tz) { try { new Intl.DateTimeFormat('en-US', { timeZone: tz }); return /^[A-Za-z0-9_+\-/]{1,64}$/.test(tz); } catch { return false; } }