@niwa-labs/commitments 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/README.md +27 -2
- package/package.json +32 -4
- package/src/cockpit/actions.ts +37 -0
- package/src/cockpit/cards.ts +45 -0
- package/src/cockpit/index.tsx +19 -0
- package/src/cockpit/page.tsx +68 -0
- package/src/index.ts +478 -0
- package/src/records.ts +232 -0
- package/test/cockpit-actions.test.ts +37 -0
- package/test/cockpit-cards.test.ts +41 -0
- package/test/commitments.test.ts +443 -0
- package/test/queries.test.ts +41 -0
- package/test/replay.test.ts +83 -0
- package/tsconfig.json +15 -0
package/src/records.ts
ADDED
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The records entry of commitments: the records the plugin writes and the typed references of its
|
|
3
|
+
* actions; no factory and nothing that runs.
|
|
4
|
+
*
|
|
5
|
+
* A commitment is a promise with an author, an agent whose inbox it is delivered to, and maybe a
|
|
6
|
+
* deadline. At the deadline it is delivered as a fact; when it is still not done after the grace
|
|
7
|
+
* period, it is missed. The one who made it, or the owner, says it is done; either may cancel it.
|
|
8
|
+
*
|
|
9
|
+
* An agent's own promise is its to make. A promise on the owner's behalf, or one that sets him a
|
|
10
|
+
* deadline, comes only from his own words: he makes it himself, an agent quotes a record of his
|
|
11
|
+
* that says it, or he confirms what an agent proposed. A deadline cannot be read out of his words,
|
|
12
|
+
* so a promise that carries one, or that rewords what he said, is put to him as it stands.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import { Address, EntityDescription, IdText, actionRef, getRef, idSchema, listRef, queryOf, record } from "@niwa-labs/core";
|
|
16
|
+
import type { Id, TypeQuery } from "@niwa-labs/core";
|
|
17
|
+
import { AgentName, BriefingSectionInput, BriefingSectionOutput } from "@niwa-labs/agent/records";
|
|
18
|
+
import { QuestionName, RequestId } from "@niwa-labs/requests/records";
|
|
19
|
+
import { z } from "zod";
|
|
20
|
+
|
|
21
|
+
/** The id of a commitment, `com-3fa9c2`. */
|
|
22
|
+
export const CommitmentId = idSchema("commitment");
|
|
23
|
+
export type CommitmentId = Id<"commitment">;
|
|
24
|
+
|
|
25
|
+
/** Who a promise binds: the one who makes it, or the owner. */
|
|
26
|
+
export const CommitmentParty = z.enum(["self", "owner"]);
|
|
27
|
+
export type CommitmentParty = z.infer<typeof CommitmentParty>;
|
|
28
|
+
|
|
29
|
+
/** The last moment a date can hold, in milliseconds since the epoch. */
|
|
30
|
+
export const MAX_MOMENT = 8_640_000_000_000_000;
|
|
31
|
+
|
|
32
|
+
/** A moment in milliseconds since the epoch, one a date can hold. */
|
|
33
|
+
export const Moment = z.number().int().nonnegative().max(MAX_MOMENT);
|
|
34
|
+
|
|
35
|
+
/** Why a commitment stands: whose word made it. */
|
|
36
|
+
export const CommitmentBasis = z.discriminatedUnion("kind", [
|
|
37
|
+
/** The one who made it promised it for itself. */
|
|
38
|
+
z.strictObject({ kind: z.literal("own") }),
|
|
39
|
+
/** The owner made it himself. */
|
|
40
|
+
z.strictObject({ kind: z.literal("owner") }),
|
|
41
|
+
/** An agent made it from a record of the owner's words: a message or a turn he wrote, which holds the promise as worded. */
|
|
42
|
+
z.strictObject({ kind: z.literal("owner-words"), record: z.string().min(1) }),
|
|
43
|
+
/** The owner confirmed what an agent proposed, by answering this request. */
|
|
44
|
+
z.strictObject({ kind: z.literal("owner-confirmed"), request: RequestId }),
|
|
45
|
+
]);
|
|
46
|
+
export type CommitmentBasis = z.infer<typeof CommitmentBasis>;
|
|
47
|
+
|
|
48
|
+
/** What every commitment says about itself, proposed or made. */
|
|
49
|
+
const Terms = {
|
|
50
|
+
id: CommitmentId,
|
|
51
|
+
/** What is promised. */
|
|
52
|
+
text: z.string().min(1),
|
|
53
|
+
/** A few words a person reads in a list. */
|
|
54
|
+
description: EntityDescription,
|
|
55
|
+
/** Who made it. */
|
|
56
|
+
by: Address,
|
|
57
|
+
/** The agent whose inbox it is delivered to when it comes due. */
|
|
58
|
+
to: AgentName,
|
|
59
|
+
party: CommitmentParty,
|
|
60
|
+
/** The deadline. A commitment without one is open until it is done or cancelled. */
|
|
61
|
+
due: Moment.optional(),
|
|
62
|
+
};
|
|
63
|
+
|
|
64
|
+
type Phase = CommitmentStatus | "new";
|
|
65
|
+
|
|
66
|
+
/** Check transitions against the last committed status of this promise. */
|
|
67
|
+
function transition(next: CommitmentStatus, ...from: Phase[]) {
|
|
68
|
+
return { guard: {
|
|
69
|
+
group: "commitment",
|
|
70
|
+
key: (data: { id: string; basedOn?: Phase }) => data.id,
|
|
71
|
+
initial: (): Phase => "new",
|
|
72
|
+
admit: (phase: Phase, data: { id: string; basedOn?: Phase }) =>
|
|
73
|
+
from.includes(phase) && (data.basedOn === undefined || data.basedOn === phase)
|
|
74
|
+
? undefined : { code: "commitment-closed", reason: `commitment ${data.id} is ${phase}` },
|
|
75
|
+
fold: (phase: Phase): Phase => next === "kept" && phase === "missed" ? "kept-late" : next,
|
|
76
|
+
} };
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** A commitment was made: it stands from now on. */
|
|
80
|
+
export const CommitmentMade = record("commitment.made", z.object({ ...Terms, basis: CommitmentBasis }), transition("open", "new", "proposed"));
|
|
81
|
+
|
|
82
|
+
/** An agent proposed a commitment for the owner: it stands only when he confirms it. */
|
|
83
|
+
export const CommitmentProposed = record("commitment.proposed", z.object(Terms), transition("proposed", "new"));
|
|
84
|
+
|
|
85
|
+
/** The owner did not confirm a proposed commitment. */
|
|
86
|
+
export const CommitmentDeclined = record("commitment.declined", z.object({ id: CommitmentId, request: RequestId.optional() }), transition("declined", "proposed"));
|
|
87
|
+
|
|
88
|
+
/** A commitment came due and was delivered to its agent's inbox. */
|
|
89
|
+
export const CommitmentDelivered = record("commitment.delivered", z.object({ id: CommitmentId, due: Moment, at: Moment }), transition("due", "open"));
|
|
90
|
+
|
|
91
|
+
/** A commitment was done. */
|
|
92
|
+
export const CommitmentKept = record(
|
|
93
|
+
"commitment.kept",
|
|
94
|
+
z.object({ id: CommitmentId, basedOn: z.enum(["open", "due", "missed"]), by: Address.optional(), note: z.string().min(1).optional() }),
|
|
95
|
+
transition("kept", "open", "due", "missed"),
|
|
96
|
+
);
|
|
97
|
+
|
|
98
|
+
/** A commitment was not done by its deadline and the grace after it. */
|
|
99
|
+
export const CommitmentMissed = record("commitment.missed", z.object({ id: CommitmentId, due: Moment, at: Moment }), transition("missed", "open", "due"));
|
|
100
|
+
|
|
101
|
+
/** A commitment was cancelled: it is no longer promised. */
|
|
102
|
+
export const CommitmentCancelled = record(
|
|
103
|
+
"commitment.cancelled",
|
|
104
|
+
z.object({ id: CommitmentId, basedOn: z.enum(["open", "due", "proposed"]), by: Address.optional(), reason: z.string().min(1).optional() }),
|
|
105
|
+
transition("cancelled", "open", "due", "proposed"),
|
|
106
|
+
);
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* The records of one commitment, as a script waits for or reads them with their data typed:
|
|
110
|
+
* `await wait(commitmentKept(id), { timeout: "2h" })`. A text that is not the id of a commitment is
|
|
111
|
+
* refused here.
|
|
112
|
+
*/
|
|
113
|
+
export function commitmentMade(id: string): TypeQuery<z.output<typeof CommitmentMade.schema>> {
|
|
114
|
+
return queryOf(CommitmentMade, { id: CommitmentId.parse(id) });
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** A proposal of one commitment. */
|
|
118
|
+
export function commitmentProposed(id: string): TypeQuery<z.output<typeof CommitmentProposed.schema>> {
|
|
119
|
+
return queryOf(CommitmentProposed, { id: CommitmentId.parse(id) });
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/** The owner did not confirm one proposed commitment. */
|
|
123
|
+
export function commitmentDeclined(id: string): TypeQuery<z.output<typeof CommitmentDeclined.schema>> {
|
|
124
|
+
return queryOf(CommitmentDeclined, { id: CommitmentId.parse(id) });
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** One commitment came due and was delivered to its agent's inbox. */
|
|
128
|
+
export function commitmentDelivered(id: string): TypeQuery<z.output<typeof CommitmentDelivered.schema>> {
|
|
129
|
+
return queryOf(CommitmentDelivered, { id: CommitmentId.parse(id) });
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** One commitment was done. */
|
|
133
|
+
export function commitmentKept(id: string): TypeQuery<z.output<typeof CommitmentKept.schema>> {
|
|
134
|
+
return queryOf(CommitmentKept, { id: CommitmentId.parse(id) });
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/** One commitment was not done by its deadline and the grace after it. */
|
|
138
|
+
export function commitmentMissed(id: string): TypeQuery<z.output<typeof CommitmentMissed.schema>> {
|
|
139
|
+
return queryOf(CommitmentMissed, { id: CommitmentId.parse(id) });
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** One commitment was cancelled. */
|
|
143
|
+
export function commitmentCancelled(id: string): TypeQuery<z.output<typeof CommitmentCancelled.schema>> {
|
|
144
|
+
return queryOf(CommitmentCancelled, { id: CommitmentId.parse(id) });
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/** The record types the plugin declares. */
|
|
148
|
+
export const COMMITMENT_TYPES = [
|
|
149
|
+
CommitmentProposed,
|
|
150
|
+
CommitmentMade,
|
|
151
|
+
CommitmentDeclined,
|
|
152
|
+
CommitmentDelivered,
|
|
153
|
+
CommitmentKept,
|
|
154
|
+
CommitmentMissed,
|
|
155
|
+
CommitmentCancelled,
|
|
156
|
+
] as const;
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Where a commitment stands: proposed to the owner, open, due (delivered and waiting to be done),
|
|
160
|
+
* or how it ended.
|
|
161
|
+
*/
|
|
162
|
+
export const CommitmentStatus = z.enum(["proposed", "open", "due", "kept", "kept-late", "missed", "cancelled", "declined"]);
|
|
163
|
+
export type CommitmentStatus = z.infer<typeof CommitmentStatus>;
|
|
164
|
+
|
|
165
|
+
/** Commitments in these states have left the active list. A missed one can still be kept late. */
|
|
166
|
+
export const ENDED: readonly CommitmentStatus[] = ["kept", "kept-late", "missed", "cancelled", "declined"];
|
|
167
|
+
|
|
168
|
+
/** The name of the question that asks the owner to confirm a proposed commitment. */
|
|
169
|
+
export const CONFIRM_QUESTION: QuestionName = QuestionName.parse("commitment.confirm");
|
|
170
|
+
|
|
171
|
+
export const commitmentMake = actionRef("commitment.make", {
|
|
172
|
+
description:
|
|
173
|
+
"Makes a commitment: what is promised, the agent whose inbox it is delivered to at its deadline, and the deadline if it has one, in milliseconds since the epoch. Your own promise (party self) stands at once. A promise on the owner's behalf or one that sets him a deadline (party owner) stands only from his words: cite a record he wrote that holds the promise as you word it, with no deadline of your own (basis owner-words). Otherwise, including any promise with a deadline, it is proposed to him and stands once he confirms it himself. Every commitment is listed with a way to cancel it.",
|
|
174
|
+
input: z.strictObject({
|
|
175
|
+
text: z.string().min(1),
|
|
176
|
+
description: EntityDescription.optional(),
|
|
177
|
+
to: AgentName,
|
|
178
|
+
party: CommitmentParty.default("self"),
|
|
179
|
+
due: Moment.optional(),
|
|
180
|
+
/** The record of the owner's words a promise for him is made from. */
|
|
181
|
+
basis: z.strictObject({ kind: z.literal("owner-words"), record: z.string().min(1) }).optional(),
|
|
182
|
+
}),
|
|
183
|
+
output: z.object({ id: CommitmentId, status: z.enum(["open", "proposed"]) }),
|
|
184
|
+
});
|
|
185
|
+
|
|
186
|
+
export const commitmentDone = actionRef("commitment.done", {
|
|
187
|
+
description: "Says a commitment is done. Only the one who made it, or the owner, may.",
|
|
188
|
+
input: z.strictObject({ id: IdText, note: z.string().min(1).optional() }),
|
|
189
|
+
output: z.object({ id: CommitmentId, status: CommitmentStatus }),
|
|
190
|
+
});
|
|
191
|
+
|
|
192
|
+
export const commitmentCancel = actionRef("commitment.cancel", {
|
|
193
|
+
description:
|
|
194
|
+
"Cancels a commitment that has not ended. The owner may cancel any; the one who made it may cancel its own promise, not one made for the owner.",
|
|
195
|
+
input: z.strictObject({ id: IdText, reason: z.string().min(1).optional() }),
|
|
196
|
+
output: z.object({ id: CommitmentId, status: CommitmentStatus }),
|
|
197
|
+
});
|
|
198
|
+
|
|
199
|
+
export const commitmentList = listRef("commitment.list", {
|
|
200
|
+
kind: "commitment",
|
|
201
|
+
noun: "commitment",
|
|
202
|
+
detail: "Oldest first; the filters narrow by where it stands and by the agent it is delivered to.",
|
|
203
|
+
filter: { status: CommitmentStatus.optional(), to: AgentName.optional() },
|
|
204
|
+
item: { by: Address, canCancel: z.boolean(), status: CommitmentStatus, party: CommitmentParty, to: AgentName, due: Moment.optional() },
|
|
205
|
+
});
|
|
206
|
+
|
|
207
|
+
/** One commitment, whole. */
|
|
208
|
+
export const CommitmentEntity = z.object({
|
|
209
|
+
...Terms,
|
|
210
|
+
status: CommitmentStatus,
|
|
211
|
+
/** Whose word it stands on; absent while it is proposed. */
|
|
212
|
+
basis: CommitmentBasis.optional(),
|
|
213
|
+
/** Who ended it, when it was done or cancelled by an address. */
|
|
214
|
+
endedBy: Address.optional(),
|
|
215
|
+
/** What was said when it ended: the note of a done one, the reason of a cancelled one. */
|
|
216
|
+
note: z.string().optional(),
|
|
217
|
+
});
|
|
218
|
+
export type CommitmentEntity = z.infer<typeof CommitmentEntity>;
|
|
219
|
+
|
|
220
|
+
export const commitmentGet = getRef("commitment.get", {
|
|
221
|
+
kind: "commitment",
|
|
222
|
+
noun: "commitment",
|
|
223
|
+
detail: "It carries what was promised, who made it, whose word it stands on and where it stands.",
|
|
224
|
+
entity: CommitmentEntity,
|
|
225
|
+
});
|
|
226
|
+
|
|
227
|
+
/** The section of an agent's briefing: the commitments delivered to it or made by it that have not ended. */
|
|
228
|
+
export const commitmentBriefing = actionRef("commitment.briefing", {
|
|
229
|
+
description: "The open commitments of an agent, one line each: the ones delivered to it and the ones it made.",
|
|
230
|
+
input: BriefingSectionInput,
|
|
231
|
+
output: BriefingSectionOutput,
|
|
232
|
+
});
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
// The copy of the commitment actions the cockpit module keeps reads what the host answers and sends what it takes.
|
|
2
|
+
|
|
3
|
+
import { expect, test } from "bun:test";
|
|
4
|
+
import { actionName } from "@niwa-labs/core";
|
|
5
|
+
import { plugin } from "@niwa-labs/plugin";
|
|
6
|
+
import { baseStack, createNiwa, tempHome, unreadable, unsendable } from "@niwa-labs/testing";
|
|
7
|
+
|
|
8
|
+
import { commitments } from "../src/index.ts";
|
|
9
|
+
import { commitmentCancel, commitmentList } from "../src/records.ts";
|
|
10
|
+
import { cancelAction, listAction } from "../src/cockpit/actions.ts";
|
|
11
|
+
|
|
12
|
+
test("the cards are read from what the host answers", () => {
|
|
13
|
+
expect(String(listAction.name)).toBe(String(commitmentList.name));
|
|
14
|
+
expect(unsendable(listAction.input, commitmentList.input)).toEqual([]);
|
|
15
|
+
expect(unreadable(listAction.output, commitmentList.output)).toEqual([]);
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
test("a card's cancel sends what the host takes", () => {
|
|
19
|
+
expect(String(cancelAction.name)).toBe(String(commitmentCancel.name));
|
|
20
|
+
expect(unsendable(cancelAction.input, commitmentCancel.input)).toEqual([]);
|
|
21
|
+
expect(unreadable(cancelAction.output, commitmentCancel.output)).toEqual([]);
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
test("the plugin offers its cards to the cockpit", async () => {
|
|
25
|
+
const home = await tempHome();
|
|
26
|
+
const niwa = createNiwa({ home: home.path });
|
|
27
|
+
try {
|
|
28
|
+
// Commitments deliver through the agents plugin and wait on the timers: a host that has them.
|
|
29
|
+
niwa.use(...baseStack().plugins, plugin("agents", () => {}), commitments());
|
|
30
|
+
await niwa.serve();
|
|
31
|
+
const catalog = (await niwa.call(actionName("niwa.cockpit.catalog"), {})) as { modules: Array<{ id: string; package: string }> };
|
|
32
|
+
expect(catalog.modules.map((one) => one.id)).toContain("commitments");
|
|
33
|
+
} finally {
|
|
34
|
+
await niwa.close();
|
|
35
|
+
await home.cleanup();
|
|
36
|
+
}
|
|
37
|
+
});
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
// The commitment cards: which ring each status is drawn with, and which commitments a card can still cancel.
|
|
2
|
+
|
|
3
|
+
import { expect, test } from "bun:test";
|
|
4
|
+
|
|
5
|
+
import { createViewer } from "@niwa-labs/cockpit-sdk";
|
|
6
|
+
|
|
7
|
+
import { CommitmentStatus } from "../src/cockpit/actions.ts";
|
|
8
|
+
import { RING, canCancel, cancellable, commitmentsByStatus } from "../src/cockpit/cards.ts";
|
|
9
|
+
|
|
10
|
+
test("a commitment can be cancelled until it ends", () => {
|
|
11
|
+
expect(CommitmentStatus.options.filter(cancellable)).toEqual(["proposed", "open", "due"]);
|
|
12
|
+
});
|
|
13
|
+
|
|
14
|
+
test("open commitments show nearest deadlines first and completed ones stay in the history", () => {
|
|
15
|
+
const { open, history } = commitmentsByStatus([
|
|
16
|
+
{ id: "no deadline", status: "open" },
|
|
17
|
+
{ id: "already kept", status: "kept", due: 2 },
|
|
18
|
+
{ id: "later", status: "proposed", due: 30 },
|
|
19
|
+
{ id: "now", status: "due", due: 10 },
|
|
20
|
+
] as const);
|
|
21
|
+
expect(open.map(({ id }) => id)).toEqual(["now", "later", "no deadline"]);
|
|
22
|
+
expect(history.map(({ id }) => id)).toEqual(["already kept"]);
|
|
23
|
+
});
|
|
24
|
+
|
|
25
|
+
test("every status has a ring, and an ended one is not drawn as still going", () => {
|
|
26
|
+
expect(Object.keys(RING).sort()).toEqual([...CommitmentStatus.options].sort());
|
|
27
|
+
expect(RING.kept).toBe("done");
|
|
28
|
+
expect(RING.missed).toBe("failed");
|
|
29
|
+
expect(RING.cancelled).toBe("stopped");
|
|
30
|
+
expect(RING.due).toBe("running");
|
|
31
|
+
});
|
|
32
|
+
|
|
33
|
+
test("a card offers a cancel to the viewer who may call it and could be let", () => {
|
|
34
|
+
const owner = createViewer({ id: "owner", owner: true, actions: ["commitment.cancel"] });
|
|
35
|
+
const agent = createViewer({ id: "session:rin", owner: false, actions: ["commitment.cancel"] });
|
|
36
|
+
const reader = createViewer({ id: "reader", owner: false, actions: ["commitment.list"] });
|
|
37
|
+
expect(canCancel({ canCancel: true }, owner)).toBe(true);
|
|
38
|
+
expect(canCancel({ canCancel: false }, agent)).toBe(false);
|
|
39
|
+
expect(canCancel({ canCancel: true }, agent)).toBe(true);
|
|
40
|
+
expect(canCancel({ canCancel: true }, reader)).toBe(false);
|
|
41
|
+
});
|