@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 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
- # Temporary Holding Version
1
+ # @niwa-labs/rin
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
+ 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-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
+ "./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
+ }
@@ -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
+ });