@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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Niwa Labs contributors
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/README.md CHANGED
@@ -1,3 +1,28 @@
1
- # Temporary Holding Version
1
+ # @niwa-labs/commitments
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A plugin for commitments: what was promised, by when, delivery, and whether it was kept.
4
+
5
+ - `commitment.make` records a promise: its text, the agent whose inbox it is delivered to, and an
6
+ optional deadline. An agent's own promise (`party: "self"`) stands at once.
7
+ - A promise on the owner's behalf or one that sets him a deadline (`party: "owner"`) stands only on
8
+ his word: he makes it himself, an agent cites a record he wrote that holds the promise as worded
9
+ (`basis: owner-words`; a message, sent or received, or a turn of his), or it is proposed to him as
10
+ a `commitment.confirm` question and stands once he says yes himself. A promise that carries a
11
+ deadline, or rewords what he said, is always proposed: a deadline cannot be read out of words, and
12
+ an answer a resolver found for him confirms nothing.
13
+ - At the deadline an open commitment is told to its agent through `agent.notify`, and is delivered
14
+ once the inbox took it; when it is still not done after the grace period (an hour by default), it
15
+ is missed whether it was delivered or not, and the agent is told. A deadline and its grace must
16
+ fit in a date. Completing a missed promise changes its status to `kept-late`.
17
+ - `commitment.done` and `commitment.cancel` end it: the one who made it or the owner may; only the
18
+ owner cancels a promise made for him. `commitment.list` and `commitment.get` show every one, and
19
+ the list includes its maker and whether the caller can cancel it. Each agent's briefing gets a section of its open commitments. In the cockpit every commitment is
20
+ a card with a cancel button for the viewer who may use it (`./cockpit`).
21
+
22
+ A script waits for or reads one commitment with the data typed, through the builders of
23
+ `@niwa-labs/commitments/records`: `await wait(commitmentKept(id), { timeout: "2h" })`, and likewise
24
+ `commitmentMissed`, `commitmentDelivered`, `commitmentCancelled`, `commitmentDeclined`, `commitmentMade`
25
+ and `commitmentProposed`.
26
+
27
+ The deadline is a sleep of `@niwa-labs/timer`, asked through `timer.sleep.request`; the inbox is
28
+ `@niwa-labs/agent`'s, so a host with commitments installs both.
package/package.json CHANGED
@@ -1,6 +1,34 @@
1
1
  {
2
2
  "name": "@niwa-labs/commitments",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.0",
4
+ "license": "MIT",
5
+ "type": "module",
6
+ "exports": {
7
+ ".": "./src/index.ts",
8
+ "./records": "./src/records.ts",
9
+ "./cockpit": "./src/cockpit/index.tsx"
10
+ },
11
+ "dependencies": {
12
+ "@niwa-labs/agent": "*",
13
+ "@niwa-labs/cockpit-sdk": "*",
14
+ "@niwa-labs/core": "*",
15
+ "@niwa-labs/plugin": "*",
16
+ "@niwa-labs/requests": "*",
17
+ "@niwa-labs/timer": "*",
18
+ "@niwa-labs/ui-kit": "*",
19
+ "zod": "^4.6.7"
20
+ },
21
+ "devDependencies": {
22
+ "@niwa-labs/testing": "*",
23
+ "@tanstack/react-query": "^5.108.2",
24
+ "@types/react": "^19.3.0",
25
+ "@types/react-dom": "^19.3.0",
26
+ "react": "^19.3.1",
27
+ "react-dom": "^19.3.1"
28
+ },
29
+ "peerDependencies": {
30
+ "@tanstack/react-query": "^5.108.2",
31
+ "react": "^19.3.1",
32
+ "react-dom": "^19.3.1"
33
+ }
34
+ }
@@ -0,0 +1,37 @@
1
+ /**
2
+ * The commitment actions as the cockpit calls them: name and the part of each schema the page reads.
3
+ *
4
+ * The module runs in the browser and cannot import the host-side schemas, which reach for Node. A field the host
5
+ * stopped sending fails the page that reads it, which `test/cockpit-actions.test.ts` checks against the real actions.
6
+ */
7
+
8
+ import { z } from "zod";
9
+
10
+ export const Address = z.object({ kind: z.string(), id: z.string().optional(), harness: z.string().optional() }).loose();
11
+
12
+ export const CommitmentStatus = z.enum(["proposed", "open", "due", "kept", "kept-late", "missed", "cancelled", "declined"]);
13
+ export type CommitmentStatus = z.infer<typeof CommitmentStatus>;
14
+
15
+ export const CommitmentItem = z.object({
16
+ id: z.string(),
17
+ description: z.string(),
18
+ status: CommitmentStatus,
19
+ by: Address,
20
+ canCancel: z.boolean(),
21
+ party: z.enum(["self", "owner"]),
22
+ to: z.string(),
23
+ due: z.number().optional(),
24
+ });
25
+ export type CommitmentItem = z.infer<typeof CommitmentItem>;
26
+
27
+ export const listAction = {
28
+ name: "commitment.list",
29
+ input: z.object({ status: CommitmentStatus.optional() }),
30
+ output: z.object({ items: z.array(CommitmentItem) }),
31
+ } as const;
32
+
33
+ export const cancelAction = {
34
+ name: "commitment.cancel",
35
+ input: z.object({ id: z.string(), reason: z.string().optional() }),
36
+ output: z.object({ id: z.string(), status: CommitmentStatus }),
37
+ } as const;
@@ -0,0 +1,45 @@
1
+ /** What a commitment card shows of where a commitment stands. */
2
+
3
+ import type { Viewer } from "@niwa-labs/cockpit-sdk";
4
+ import type { WorkState } from "@niwa-labs/ui-kit";
5
+
6
+ import { cancelAction } from "./actions.ts";
7
+ import type { CommitmentItem, CommitmentStatus } from "./actions.ts";
8
+
9
+ export const RING: Record<CommitmentStatus, WorkState> = {
10
+ proposed: "waiting",
11
+ open: "pending",
12
+ due: "running",
13
+ kept: "done",
14
+ "kept-late": "done",
15
+ missed: "failed",
16
+ cancelled: "stopped",
17
+ declined: "skipped",
18
+ };
19
+
20
+ export const STATUS_LABEL: Record<CommitmentStatus, string> = {
21
+ proposed: "Ждёт подтверждения",
22
+ open: "Открыто",
23
+ due: "Срок наступил",
24
+ kept: "Выполнено",
25
+ "kept-late": "Выполнено с опозданием",
26
+ missed: "Просрочено",
27
+ cancelled: "Отменено",
28
+ declined: "Отклонено",
29
+ };
30
+
31
+ export function commitmentsByStatus<T extends Pick<CommitmentItem, "status" | "due">>(items: readonly T[]) {
32
+ const open = items.filter((item) => cancellable(item.status));
33
+ open.sort((a, b) => (a.due ?? Infinity) - (b.due ?? Infinity));
34
+ return { open, history: items.filter((item) => !cancellable(item.status)) };
35
+ }
36
+
37
+ /** Whether a commitment may still be cancelled: it has not ended. */
38
+ export function cancellable(status: CommitmentStatus): boolean {
39
+ return status === "proposed" || status === "open" || status === "due";
40
+ }
41
+
42
+ /** Show the cancel control when both the caller's grant and the promise allow it. */
43
+ export function canCancel(commitment: Pick<CommitmentItem, "canCancel">, viewer: Pick<Viewer, "can">): boolean {
44
+ return commitment.canCancel && viewer.can(cancelAction);
45
+ }
@@ -0,0 +1,19 @@
1
+ /** The cockpit module of the commitments plugin: every commitment as a card, with a way to cancel it. */
2
+
3
+ import { definePlugin } from "@niwa-labs/cockpit-sdk";
4
+
5
+ import { CommitmentsPage } from "./page.tsx";
6
+
7
+ export default definePlugin({
8
+ id: "commitments",
9
+ setup(ctx) {
10
+ ctx.pages.add({
11
+ path: "/commitments",
12
+ title: "Обязательства",
13
+ commandHeading: true,
14
+ nav: { order: 45 },
15
+ commands: [{ action: "commitment.make", label: "Добавить обязательство" }],
16
+ component: CommitmentsPage,
17
+ });
18
+ },
19
+ });
@@ -0,0 +1,68 @@
1
+ /** The commitments of the host, one card each: what was promised, by when, where it stands, and a cancel. */
2
+
3
+ import { useAction, useCall, useViewer } from "@niwa-labs/cockpit-sdk";
4
+ import { Button, CopyValue, StateRing } from "@niwa-labs/ui-kit";
5
+
6
+ import { cancelAction, listAction, type CommitmentItem } from "./actions.ts";
7
+ import { RING, STATUS_LABEL, canCancel, commitmentsByStatus } from "./cards.ts";
8
+
9
+ function CommitmentCard({ commitment }: { commitment: CommitmentItem }) {
10
+ const cancel = useAction(cancelAction);
11
+ const viewer = useViewer();
12
+ return (
13
+ <li data-slot="commitment-card" data-status={commitment.status} className="min-w-0" style={{ display: "grid", gridTemplateColumns: "auto minmax(0, 1fr)", alignItems: "start", gap: "0.3rem 0.75rem", paddingBlock: "0.6rem" }}>
14
+ <StateRing state={RING[commitment.status]} label={STATUS_LABEL[commitment.status]} />
15
+ <div className="flex min-w-0 flex-wrap items-start justify-between gap-2">
16
+ <div className="min-w-0 flex-1">
17
+ <p className="break-words text-sm font-medium">{commitment.description}</p>
18
+ <p className="desk-tools mt-1 text-xs text-muted-foreground">
19
+ <span>{STATUS_LABEL[commitment.status]}</span>
20
+ <span>Получатель {commitment.to}</span>
21
+ {commitment.due === undefined ? <span>Без срока</span> : <time dateTime={new Date(commitment.due).toISOString()}>До {new Date(commitment.due).toLocaleString("ru")}</time>}
22
+ {commitment.party === "owner" ? <span>От имени владельца</span> : null}
23
+ </p>
24
+ </div>
25
+ {canCancel(commitment, viewer) ? (
26
+ <Button variant="outline" size="sm" disabled={cancel.isPending} onClick={() => cancel.mutate({ id: commitment.id })}>
27
+ Отменить
28
+ </Button>
29
+ ) : null}
30
+ </div>
31
+ <div className="desk-tools min-w-0 text-xs text-muted-foreground" style={{ gridColumn: 2 }}>
32
+ <span>Автор {commitment.by.kind === "owner" ? "владелец" : [commitment.by.harness, commitment.by.id].filter(Boolean).join("/") || commitment.by.kind}</span>
33
+ <CopyValue value={commitment.id} />
34
+ {cancel.isError ? <span role="alert" className="text-destructive">{cancel.error.message}</span> : null}
35
+ </div>
36
+ </li>
37
+ );
38
+ }
39
+
40
+ export function CommitmentsPage() {
41
+ const commitments = useCall(listAction, {}, { refreshOn: { types: ["commitment.*"] } });
42
+ const { open, history } = commitmentsByStatus(commitments.data?.items ?? []);
43
+ const list = (items: CommitmentItem[]) => (
44
+ <ul data-slot="commitments" className="divide-y rounded-lg border bg-card px-3">
45
+ {items.map((commitment) => <CommitmentCard key={commitment.id} commitment={commitment} />)}
46
+ </ul>
47
+ );
48
+ return (
49
+ <div className="desk-page">
50
+ {commitments.isPending ? (
51
+ <p className="text-sm text-muted-foreground">Загружаем обязательства…</p>
52
+ ) : commitments.isError ? (
53
+ <p role="alert" className="text-sm text-destructive">Не удалось загрузить обязательства. {commitments.error.message}</p>
54
+ ) : (
55
+ <>
56
+ <section className="flex min-w-0 flex-col gap-2">
57
+ <h3 className="text-sm font-semibold">Открытые обязательства</h3>
58
+ {open.length ? list(open) : <p className="text-sm text-muted-foreground">Открытых обязательств нет.</p>}
59
+ </section>
60
+ {history.length ? <details className="flex min-w-0 flex-col gap-2">
61
+ <summary className="cursor-pointer text-sm font-medium">Завершённые обязательства ({history.length})</summary>
62
+ {list(history)}
63
+ </details> : null}
64
+ </>
65
+ )}
66
+ </div>
67
+ );
68
+ }