@niwa-labs/delegate 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 +30 -2
- package/package.json +17 -4
- package/src/context.ts +70 -0
- package/src/index.ts +572 -0
- package/src/records.ts +120 -0
- package/test/context.test.ts +78 -0
- package/test/delegate.test.ts +622 -0
- package/tsconfig.json +6 -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,31 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @niwa-labs/delegate
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A plugin that answers on behalf of the owner: recalling past decisions in a domain, deciding within set bounds, passing to a judge or forwarding.
|
|
4
|
+
|
|
5
|
+
`delegate({ agent: "rin", judges, context })` watches the requests put to one agent:
|
|
6
|
+
|
|
7
|
+
- **Recall.** When the owner already decided the same question (its name and what was asked,
|
|
8
|
+
without the area) in the same area, the request is answered from that decision.
|
|
9
|
+
`delegate.recall` asks the same, optionally as of a journal position; `delegate.revoke` (the
|
|
10
|
+
owner's) stops a decision from being recalled. An answer that picks an option for one time only
|
|
11
|
+
(`allow_once`, `reject_once`) is kept as a decision but never recalled.
|
|
12
|
+
- **Decide within bounds.** `delegate.decide` answers an open request with a decision of the
|
|
13
|
+
caller. Its grant target is the area (`delegate.decide@style`), and the area must be the one the
|
|
14
|
+
request names. The answer must be one the question takes, and a request is decided once. A
|
|
15
|
+
decision the request did not take, because it ended otherwise first, is revoked.
|
|
16
|
+
- **Judge.** A request of an area with a judge goes to that address first, with the context the
|
|
17
|
+
data owners give. Unanswered in time (an hour by default), it goes on to the owner.
|
|
18
|
+
- **Forward.** Everything else goes to the owner; his answer answers the request and becomes his
|
|
19
|
+
decision in that area. When the question of the request refuses the answer (a form held to more
|
|
20
|
+
than its schema says), he is asked again, up to three times, and then the request is cancelled.
|
|
21
|
+
|
|
22
|
+
Whatever was passed on for a request is withdrawn when the request is over without it; when the
|
|
23
|
+
owner cancels a forward, the request is cancelled.
|
|
24
|
+
|
|
25
|
+
Delegate does not import memory. Before a judge is asked it sends each action named in `context`
|
|
26
|
+
(a memory serves `memory.context`) a request for context: whose memory, what is needed, for whom
|
|
27
|
+
and why, read as of the request's position. It reads back the conclusions with where each holds
|
|
28
|
+
and their sources (the memory's address, the note and the journal position), and how many were
|
|
29
|
+
withheld. The types and
|
|
30
|
+
`contextSource(name)` are in `@niwa-labs/delegate/records`, which a memory may import to keep its
|
|
31
|
+
action in step with them.
|
package/package.json
CHANGED
|
@@ -1,6 +1,19 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niwa-labs/delegate",
|
|
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
|
+
"./records": "./src/records.ts"
|
|
9
|
+
},
|
|
10
|
+
"dependencies": {
|
|
11
|
+
"@niwa-labs/core": "*",
|
|
12
|
+
"@niwa-labs/plugin": "*",
|
|
13
|
+
"@niwa-labs/requests": "*",
|
|
14
|
+
"zod": "^4.6.7"
|
|
15
|
+
},
|
|
16
|
+
"devDependencies": {
|
|
17
|
+
"@niwa-labs/testing": "*"
|
|
18
|
+
}
|
|
19
|
+
}
|
package/src/context.ts
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The request for context: what delegate asks a data owner, and what it reads of the answer.
|
|
3
|
+
*
|
|
4
|
+
* Delegate never reads another plugin's data itself. It says what it needs, of whose memory, for whom
|
|
5
|
+
* and why; the plugin that owns the data answers with conclusions, each with its source: the address
|
|
6
|
+
* of the memory that holds it, the note, and the journal position it stood at. A memory serves this as
|
|
7
|
+
* `memory.context`; delegate knows the action only by the name its composition gives, and the types
|
|
8
|
+
* here are the part of that action it sends and reads. A memory imports them from this entry to keep
|
|
9
|
+
* the two in step.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { Address, actionRef } from "@niwa-labs/core";
|
|
13
|
+
import type { ActionRef } from "@niwa-labs/core";
|
|
14
|
+
import { z } from "zod";
|
|
15
|
+
|
|
16
|
+
/** A position in the journal: the sequence number of a record. */
|
|
17
|
+
export const JournalPosition = z.number().int().nonnegative();
|
|
18
|
+
export type JournalPosition = z.infer<typeof JournalPosition>;
|
|
19
|
+
|
|
20
|
+
/** What a caller asks a data owner for. */
|
|
21
|
+
export const ContextRequest = z.object({
|
|
22
|
+
/** Whose memory is read: the name of the agent it belongs to. */
|
|
23
|
+
memory: z.string().min(1),
|
|
24
|
+
/** What is needed, in a sentence: the question to be answered. */
|
|
25
|
+
query: z.string().min(1).max(500),
|
|
26
|
+
/** Why it is needed: what the reader will do with it. */
|
|
27
|
+
purpose: z.string().min(1).max(500),
|
|
28
|
+
/** Who reads what comes back. A conclusion that may not reach this address is withheld. */
|
|
29
|
+
for: Address,
|
|
30
|
+
/** Read the data as it stood at this position, so a later judgement of an old question sees the old data. */
|
|
31
|
+
at: JournalPosition.optional(),
|
|
32
|
+
});
|
|
33
|
+
export type ContextRequest = z.infer<typeof ContextRequest>;
|
|
34
|
+
|
|
35
|
+
/** Where a conclusion comes from: who holds the data, the note, and the journal position it stood at. */
|
|
36
|
+
export const SourceRef = z.object({
|
|
37
|
+
owner: Address,
|
|
38
|
+
note: z.string().min(1),
|
|
39
|
+
seq: JournalPosition,
|
|
40
|
+
});
|
|
41
|
+
export type SourceRef = z.infer<typeof SourceRef>;
|
|
42
|
+
|
|
43
|
+
/** One conclusion the data owner lets the reader have. */
|
|
44
|
+
export const ContextItem = z.object({
|
|
45
|
+
text: z.string(),
|
|
46
|
+
/** Where it holds: the project the conclusion is about. Without one it holds everywhere. */
|
|
47
|
+
project: z.string().min(1).optional(),
|
|
48
|
+
source: SourceRef,
|
|
49
|
+
});
|
|
50
|
+
export type ContextItem = z.infer<typeof ContextItem>;
|
|
51
|
+
|
|
52
|
+
/** What a data owner answers, as far as delegate reads it. */
|
|
53
|
+
export const ContextAnswer = z.object({
|
|
54
|
+
/** The position the answer was read at. */
|
|
55
|
+
at: JournalPosition,
|
|
56
|
+
items: z.array(ContextItem),
|
|
57
|
+
/** What bore on the question and was not let out to this reader. */
|
|
58
|
+
withheld: z.array(z.object({ note: z.string().min(1) })),
|
|
59
|
+
});
|
|
60
|
+
export type ContextAnswer = z.infer<typeof ContextAnswer>;
|
|
61
|
+
|
|
62
|
+
/** The action a data owner serves to answer a request for context, under the name it chooses. */
|
|
63
|
+
export function contextSource(name: string): ActionRef<ContextRequest, ContextAnswer> {
|
|
64
|
+
return actionRef(name, {
|
|
65
|
+
description:
|
|
66
|
+
"Answers a request for context: what is needed, of whose memory, for whom and why. Returns the conclusions that may reach that reader, each with its source (the memory's address, the note and the journal position), and what was withheld.",
|
|
67
|
+
input: ContextRequest,
|
|
68
|
+
output: ContextAnswer,
|
|
69
|
+
});
|
|
70
|
+
}
|