@niwa-labs/rin 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 +122 -2
- package/package.json +38 -4
- package/src/admission.ts +73 -0
- package/src/attention.ts +441 -0
- package/src/character.ts +171 -0
- package/src/charter.ts +130 -0
- package/src/cockpit/actions.ts +132 -0
- package/src/cockpit/index.tsx +13 -0
- package/src/cockpit/page.tsx +370 -0
- package/src/cockpit/view.ts +114 -0
- package/src/composition.ts +90 -0
- package/src/index.ts +16 -0
- package/src/plugin.ts +1071 -0
- package/src/presence.ts +57 -0
- package/src/records.ts +546 -0
- package/test/attention.test.ts +265 -0
- package/test/character.test.ts +42 -0
- package/test/charter.test.ts +84 -0
- package/test/cockpit-actions.test.ts +68 -0
- package/test/cockpit-view.test.ts +68 -0
- package/test/composition.test.ts +157 -0
- package/test/plugin.test.ts +988 -0
- package/test/presence.test.ts +38 -0
- package/tsconfig.json +16 -0
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,123 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @niwa-labs/rin
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Rin, an agent living inside niwa between the owner's main assistant and a
|
|
4
|
+
companion. Her centre is character and judgement: what matters to the owner,
|
|
5
|
+
when to stay quiet, when to insist, and what his corrections teach her.
|
|
6
|
+
Memory, commitments and delegation are her tools; this package also holds her
|
|
7
|
+
cockpit page.
|
|
8
|
+
|
|
9
|
+
## Composing her
|
|
10
|
+
|
|
11
|
+
Rin is the agent `agent:rin` of `@niwa-labs/agent`. `rin()` returns the
|
|
12
|
+
plugins a host installs after the agents module: a memory, commitments,
|
|
13
|
+
delegate answering for `agent:rin`, and Rin herself.
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { defaultComposition, telegram } from "@niwa-labs/niwa";
|
|
17
|
+
import { RIN_AGENT, addressingOf, rin } from "@niwa-labs/rin";
|
|
18
|
+
|
|
19
|
+
const surface = telegram({ token, owner, speaksFor: "owner", agent: RIN_AGENT });
|
|
20
|
+
const base = defaultComposition({
|
|
21
|
+
home,
|
|
22
|
+
harnesses,
|
|
23
|
+
bind: (fallback) => surface.bind(fallback),
|
|
24
|
+
// Rin is the agent `niwa agent attach` attaches to when it names none.
|
|
25
|
+
agents: { default: RIN_AGENT, roles: { assistant: "claude" } },
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
export default [
|
|
29
|
+
...base,
|
|
30
|
+
surface,
|
|
31
|
+
...rin({ bind: surface.bind(addressingOf(base)), role: "assistant", telegram: true, quietHours: { from: "23:00", to: "08:00" } }),
|
|
32
|
+
];
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Rin needs addressing, timers, the workflow and agents modules, messages, and requests. `addressingOf(plugins)` supplies the binding from sessions and agents. Each day Rin consolidates her memory when the configured quiet period ends.
|
|
36
|
+
|
|
37
|
+
The Cockpit conversation works on a local host. To configure Telegram, set `telegram: true` in Rin and `agent: RIN_AGENT` in the Telegram plugin. Rin then requires `telegram.send` at host startup. Use `say` to configure another action for proactive messages. With neither configured, Rin can hold a message for the owner's next contact.
|
|
38
|
+
|
|
39
|
+
## Character
|
|
40
|
+
|
|
41
|
+
Her character has three layers that change by different rules:
|
|
42
|
+
|
|
43
|
+
| Layer | What | Who changes it |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| Core | Who she is, her values and voice, the ceiling on warmth, no flattery, how she mends things after a mistake | The owner only: `CORE` in this package, with a version a test pins to its words |
|
|
46
|
+
| Charter | How the owner wants her to act: what matters to him, when to stay quiet, when to insist | Grows from his corrections; he confirms every rule |
|
|
47
|
+
| State | What is in progress, promised or unanswered | She keeps it, in her memory, commitments and attention |
|
|
48
|
+
|
|
49
|
+
The core is the constant section of her prompt, how she works the stable one.
|
|
50
|
+
Her sessions use only niwa's tools, through her hands (`HANDS`).
|
|
51
|
+
|
|
52
|
+
## Attention
|
|
53
|
+
|
|
54
|
+
Everything that happens reaches her inbox as a fact: a task's outcome, a
|
|
55
|
+
digest of a session attached to her, a promise falling due, and the occasions
|
|
56
|
+
of her attention — what someone tells her with `rin.notice`, an agent she
|
|
57
|
+
leads that cannot be reached, a workflow run she started that ended. For each
|
|
58
|
+
she decides with `rin.attend`: stay silent, keep a note, tell the owner at his
|
|
59
|
+
next contact, tell him now, or insist.
|
|
60
|
+
|
|
61
|
+
- An occasion is known by its key: while it holds, a repeat is counted on it
|
|
62
|
+
and does not reach her again. When it stops holding (`ends: true`), what
|
|
63
|
+
she held about it is dropped.
|
|
64
|
+
- Each occasion she is told comes with what she weighs: whether he works
|
|
65
|
+
now in an attached session, his quiet hours, the safety ceiling, and her
|
|
66
|
+
charter. `rin.context` reads the same.
|
|
67
|
+
- What she says now goes out through the action of `say`, called by the
|
|
68
|
+
plugin. During his quiet hours it waits for their end; past the safety
|
|
69
|
+
ceiling (twelve in any 24 hours by default, `ceiling`) or when it surely
|
|
70
|
+
did not reach him (the action failed saying nothing was sent: `NotSent`), it
|
|
71
|
+
waits for his next contact. A send that may have gone is not sent again: it
|
|
72
|
+
is kept as unsure, counts as told, and she is told it may not have reached him.
|
|
73
|
+
- What waits for his next contact is in her briefing, and is brought up when
|
|
74
|
+
he writes to her or attaches a session.
|
|
75
|
+
- What only waits was not told yet: a new decision about it takes the place of
|
|
76
|
+
the one that waits, so one thing is one message. What was sent or brought
|
|
77
|
+
up counts as told; saying it again is insisting, and insisting names a rule
|
|
78
|
+
of her charter that the owner confirmed.
|
|
79
|
+
- She decides about a fact that is no occasion by its turn id, which
|
|
80
|
+
`rin.inbox` lists.
|
|
81
|
+
|
|
82
|
+
## Corrections and the charter
|
|
83
|
+
|
|
84
|
+
A correction is `rin.corrected { about, what }`. The owner writes one with
|
|
85
|
+
`rin.correct`, Rin from his own words (with the id of the record that holds
|
|
86
|
+
them), and the plugin from what he does: changes, takes back or erases a
|
|
87
|
+
note of hers, cancels a promise or revokes a decision of hers, turns down or
|
|
88
|
+
leaves unanswered a question of hers, or waves away what she told him
|
|
89
|
+
(`rin.attention.dismiss`).
|
|
90
|
+
|
|
91
|
+
Two corrections about one thing that no rule covers (`ruleAfter`) ask her
|
|
92
|
+
for a rule. She words it and proposes it with `rin.charter.propose`; the
|
|
93
|
+
owner is asked, and only his own yes makes it part of the charter. A rule he
|
|
94
|
+
proposes himself stands at once; `rin.charter.retire` takes one out.
|
|
95
|
+
|
|
96
|
+
## Leading the work
|
|
97
|
+
|
|
98
|
+
She starts tasks reporting to `agent:rin` and their outcomes come back to her
|
|
99
|
+
as facts; she makes agents with `agent.create` and gives them work.
|
|
100
|
+
|
|
101
|
+
- Her own promises she makes herself. A promise on the owner's behalf, or one
|
|
102
|
+
that sets him a deadline, exists only when he worded it or confirmed the
|
|
103
|
+
deadline she proposed; every promise is a card he can cancel.
|
|
104
|
+
- Another agent gets from her memory the conclusion it needs and where it
|
|
105
|
+
holds, never her notes. Notes about the owner leave only with his answer;
|
|
106
|
+
facts about a project go to the agents of that project.
|
|
107
|
+
|
|
108
|
+
## Module installation
|
|
109
|
+
|
|
110
|
+
`selfEdit` controls installation of modules in the `rin/` group through `rin.self.install`.
|
|
111
|
+
|
|
112
|
+
- `off` is the default and disables proposals.
|
|
113
|
+
- `ask` requires a new owner decision for each installation. The request shows the module path, SHA-256 and Rin's reason.
|
|
114
|
+
- `free` lets Rin install the proposed module directly.
|
|
115
|
+
|
|
116
|
+
The journal keeps each proposal, claim and outcome. The owner can uninstall a current version from the Rin page. The selected SHA-256 identifies the version to remove.
|
|
117
|
+
|
|
118
|
+
## Cockpit
|
|
119
|
+
|
|
120
|
+
`@niwa-labs/rin/cockpit` is her page at `/rin`: the conversation with her (his
|
|
121
|
+
messages with where each stands, and what she wrote to him), writing to her, what she holds
|
|
122
|
+
and told, her charter, her promises, the top of her memory and the agents she
|
|
123
|
+
leads; and a home tile with what waits for the owner.
|
package/package.json
CHANGED
|
@@ -1,6 +1,40 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niwa-labs/rin",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": "./src/index.ts",
|
|
8
|
+
"./cockpit": "./src/cockpit/index.tsx"
|
|
9
|
+
},
|
|
10
|
+
"dependencies": {
|
|
11
|
+
"@niwa-labs/agent": "*",
|
|
12
|
+
"@niwa-labs/cockpit-sdk": "*",
|
|
13
|
+
"@niwa-labs/commitments": "*",
|
|
14
|
+
"@niwa-labs/core": "*",
|
|
15
|
+
"@niwa-labs/delegate": "*",
|
|
16
|
+
"@niwa-labs/history": "*",
|
|
17
|
+
"@niwa-labs/memory": "*",
|
|
18
|
+
"@niwa-labs/messages": "*",
|
|
19
|
+
"@niwa-labs/plugin": "*",
|
|
20
|
+
"@niwa-labs/requests": "*",
|
|
21
|
+
"@niwa-labs/script": "*",
|
|
22
|
+
"@niwa-labs/timer": "*",
|
|
23
|
+
"@niwa-labs/ui-kit": "*",
|
|
24
|
+
"@niwa-labs/workflow": "*",
|
|
25
|
+
"zod": "^4.6.7"
|
|
26
|
+
},
|
|
27
|
+
"devDependencies": {
|
|
28
|
+
"@niwa-labs/testing": "*",
|
|
29
|
+
"@tanstack/react-query": "^5.108.2",
|
|
30
|
+
"@types/react": "^19.3.0",
|
|
31
|
+
"@types/react-dom": "^19.3.0",
|
|
32
|
+
"react": "^19.3.1",
|
|
33
|
+
"react-dom": "^19.3.1"
|
|
34
|
+
},
|
|
35
|
+
"peerDependencies": {
|
|
36
|
+
"@tanstack/react-query": "^5.108.2",
|
|
37
|
+
"react": "^19.3.1",
|
|
38
|
+
"react-dom": "^19.3.1"
|
|
39
|
+
}
|
|
40
|
+
}
|
package/src/admission.ts
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import type { RecordGuard } from "@niwa-labs/core";
|
|
2
|
+
|
|
3
|
+
export interface OccasionAdmission {
|
|
4
|
+
readonly open: string | null;
|
|
5
|
+
readonly notifications: ReadonlyMap<string, "claimed" | "notified">;
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
export const occasionGuard = <T extends { key: string }>(
|
|
9
|
+
admit: RecordGuard<T, OccasionAdmission>["admit"],
|
|
10
|
+
fold: RecordGuard<T, OccasionAdmission>["fold"],
|
|
11
|
+
): { guard: RecordGuard<T, OccasionAdmission> } => ({
|
|
12
|
+
guard: {
|
|
13
|
+
group: "occasion",
|
|
14
|
+
key: (data) => data.key,
|
|
15
|
+
initial: () => ({ open: null, notifications: new Map() }),
|
|
16
|
+
admit,
|
|
17
|
+
fold,
|
|
18
|
+
},
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
interface CharterAdmission {
|
|
22
|
+
readonly corrections: ReadonlyMap<string, "new" | "asked" | "covered">;
|
|
23
|
+
readonly rules: ReadonlyMap<string, "proposed" | "ruled" | "declined" | "retired">;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export const charterGuard = <T extends { about: string }>(
|
|
27
|
+
admit: RecordGuard<T, CharterAdmission>["admit"],
|
|
28
|
+
fold: RecordGuard<T, CharterAdmission>["fold"],
|
|
29
|
+
): { guard: RecordGuard<T, CharterAdmission> } => ({
|
|
30
|
+
guard: {
|
|
31
|
+
group: "charter",
|
|
32
|
+
key: (data) => data.about,
|
|
33
|
+
initial: () => ({ corrections: new Map(), rules: new Map() }),
|
|
34
|
+
admit,
|
|
35
|
+
fold,
|
|
36
|
+
},
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
export function ruleStatus(status: "ruled" | "declined" | "retired") {
|
|
40
|
+
return charterGuard<{ about: string; rule: string }>(
|
|
41
|
+
(state, data) => {
|
|
42
|
+
const current = state.rules.get(data.rule);
|
|
43
|
+
if (current === "proposed" || (current === "ruled" && status === "retired")) return;
|
|
44
|
+
return { code: "rule-closed", reason: `Rule ${data.rule} can no longer be ${status}` };
|
|
45
|
+
},
|
|
46
|
+
(state, data) => ({ ...state, rules: new Map(state.rules).set(data.rule, status) }),
|
|
47
|
+
);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export function correctionStatus(
|
|
51
|
+
state: CharterAdmission,
|
|
52
|
+
ids: readonly string[],
|
|
53
|
+
status: "asked" | "covered",
|
|
54
|
+
): CharterAdmission {
|
|
55
|
+
const corrections = new Map(state.corrections);
|
|
56
|
+
for (const id of ids) corrections.set(id, status);
|
|
57
|
+
return { ...state, corrections };
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export const hasProposal = (state: CharterAdmission) => [...state.rules.values()].includes("proposed");
|
|
61
|
+
|
|
62
|
+
export const editGuard = <T extends { plugin: string; edit: string }>(
|
|
63
|
+
admit: RecordGuard<T, string | null>["admit"],
|
|
64
|
+
fold: RecordGuard<T, string | null>["fold"],
|
|
65
|
+
): { guard: RecordGuard<T, string | null> } => ({
|
|
66
|
+
guard: {
|
|
67
|
+
group: "self-edit",
|
|
68
|
+
key: (data) => data.plugin,
|
|
69
|
+
initial: () => null,
|
|
70
|
+
admit,
|
|
71
|
+
fold,
|
|
72
|
+
},
|
|
73
|
+
});
|