@nelsonlongxiang/dsh-open-a2a-net 0.7.0 → 0.8.1-preview.1

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.
Files changed (128) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +109 -94
  3. package/README_zh.md +64 -66
  4. package/THIRD_PARTY_NOTICES.md +12 -0
  5. package/assets/nexusDist/assets/index-BuidhKVr.css +1 -0
  6. package/assets/nexusDist/assets/index-YtYrkDJi.js +9 -0
  7. package/assets/nexusDist/index.html +2 -2
  8. package/cli/a2a.mjs +349 -20
  9. package/cordis.patch.yml +167 -0
  10. package/docs/licenses/dsh-superagent-MIT.txt +21 -0
  11. package/lib/a2a-client.js +12 -4
  12. package/lib/card.js +2 -0
  13. package/lib/cli-deposit.js +75 -4
  14. package/lib/config.js +1 -2
  15. package/lib/direct-forward.js +23 -1
  16. package/lib/faces/admin.js +31 -48
  17. package/lib/faces/wire.js +110 -71
  18. package/lib/followup-admission.js +47 -0
  19. package/lib/followup-delivery.js +19 -2
  20. package/lib/index.js +618 -389
  21. package/lib/node-self.js +1 -1
  22. package/lib/outbound-scope.js +10 -0
  23. package/lib/peer-directory.js +3 -1
  24. package/lib/queue-guard.js +1 -1
  25. package/lib/receipt.js +24 -2
  26. package/lib/skill/SKILL.md +1 -0
  27. package/lib/skill/references/cli.md +193 -21
  28. package/lib/skill/references/collaboration.md +3 -2
  29. package/lib/skill/references/superagent.md +106 -0
  30. package/lib/superagent/a2a-watch.js +587 -0
  31. package/lib/superagent/contract.js +1 -0
  32. package/lib/superagent/host/a2a-source.js +251 -0
  33. package/lib/superagent/host/executor.js +520 -0
  34. package/lib/superagent/host/index.js +1107 -0
  35. package/lib/superagent/host/policy.js +308 -0
  36. package/lib/superagent/host/pr-follow.js +158 -0
  37. package/lib/superagent/host/review-requests.js +77 -0
  38. package/lib/superagent/host/role-tools.js +137 -0
  39. package/lib/superagent/host/store.js +136 -0
  40. package/lib/superagent/host/tools.js +297 -0
  41. package/lib/superagent/source-types.js +22 -0
  42. package/lib/superagent/upstream/dsh-superagent/src/core/assignments.js +160 -0
  43. package/lib/superagent/upstream/dsh-superagent/src/core/engine.js +244 -0
  44. package/lib/superagent/upstream/dsh-superagent/src/core/errors.js +63 -0
  45. package/lib/superagent/upstream/dsh-superagent/src/core/evals.js +381 -0
  46. package/lib/superagent/upstream/dsh-superagent/src/core/ids.js +5 -0
  47. package/lib/superagent/upstream/dsh-superagent/src/core/index.js +9 -0
  48. package/lib/superagent/upstream/dsh-superagent/src/core/intake.js +68 -0
  49. package/lib/superagent/upstream/dsh-superagent/src/core/memory.js +51 -0
  50. package/lib/superagent/upstream/dsh-superagent/src/core/model.js +79 -0
  51. package/lib/superagent/upstream/dsh-superagent/src/core/part.js +71 -0
  52. package/lib/superagent/upstream/dsh-superagent/src/core/ports.js +1 -0
  53. package/lib/superagent/upstream/dsh-superagent/src/core/reasons.js +35 -0
  54. package/lib/superagent/upstream/dsh-superagent/src/core/replies.js +94 -0
  55. package/lib/superagent/upstream/dsh-superagent/src/core/stage.js +27 -0
  56. package/lib/superagent/upstream/dsh-superagent/src/core/tickets.js +487 -0
  57. package/lib/superagent/upstream/snapshot-8c32a9d.js +62 -0
  58. package/lib/task-auth.js +21 -0
  59. package/lib/task-ledger-rows.js +4 -0
  60. package/lib/task-ledger.js +69 -3
  61. package/lib/tools/info.js +13 -7
  62. package/lib/types/a2a-client.d.ts +0 -7
  63. package/lib/types/cli-deposit.d.ts +65 -1
  64. package/lib/types/config.d.ts +6 -20
  65. package/lib/types/direct-forward.d.ts +14 -0
  66. package/lib/types/faces/admin.d.ts +5 -0
  67. package/lib/types/faces/wire.d.ts +20 -57
  68. package/lib/types/followup-admission.d.ts +13 -0
  69. package/lib/types/followup-delivery.d.ts +1 -1
  70. package/lib/types/index.d.ts +0 -2
  71. package/lib/types/outbound-scope.d.ts +1 -0
  72. package/lib/types/queue-guard.d.ts +2 -0
  73. package/lib/types/receipt.d.ts +21 -1
  74. package/lib/types/superagent/a2a-watch.d.ts +227 -0
  75. package/lib/types/superagent/contract.d.ts +36 -0
  76. package/lib/types/superagent/host/a2a-source.d.ts +90 -0
  77. package/lib/types/superagent/host/executor.d.ts +132 -0
  78. package/lib/types/superagent/host/index.d.ts +340 -0
  79. package/lib/types/superagent/host/policy.d.ts +128 -0
  80. package/lib/types/superagent/host/pr-follow.d.ts +51 -0
  81. package/lib/types/superagent/host/review-requests.d.ts +36 -0
  82. package/lib/types/superagent/host/role-tools.d.ts +85 -0
  83. package/lib/types/superagent/host/store.d.ts +61 -0
  84. package/lib/types/superagent/host/tools.d.ts +32 -0
  85. package/lib/types/superagent/source-types.d.ts +218 -0
  86. package/lib/types/superagent/upstream/dsh-superagent/src/core/assignments.d.ts +53 -0
  87. package/lib/types/superagent/upstream/dsh-superagent/src/core/engine.d.ts +191 -0
  88. package/lib/types/superagent/upstream/dsh-superagent/src/core/errors.d.ts +58 -0
  89. package/lib/types/superagent/upstream/dsh-superagent/src/core/evals.d.ts +99 -0
  90. package/lib/types/superagent/upstream/dsh-superagent/src/core/ids.d.ts +1 -0
  91. package/lib/types/superagent/upstream/dsh-superagent/src/core/index.d.ts +9 -0
  92. package/lib/types/superagent/upstream/dsh-superagent/src/core/intake.d.ts +15 -0
  93. package/lib/types/superagent/upstream/dsh-superagent/src/core/memory.d.ts +40 -0
  94. package/lib/types/superagent/upstream/dsh-superagent/src/core/model.d.ts +432 -0
  95. package/lib/types/superagent/upstream/dsh-superagent/src/core/part.d.ts +49 -0
  96. package/lib/types/superagent/upstream/dsh-superagent/src/core/ports.d.ts +217 -0
  97. package/lib/types/superagent/upstream/dsh-superagent/src/core/reasons.d.ts +36 -0
  98. package/lib/types/superagent/upstream/dsh-superagent/src/core/replies.d.ts +55 -0
  99. package/lib/types/superagent/upstream/dsh-superagent/src/core/stage.d.ts +18 -0
  100. package/lib/types/superagent/upstream/dsh-superagent/src/core/tickets.d.ts +151 -0
  101. package/lib/types/superagent/upstream/snapshot-8c32a9d.d.ts +317 -0
  102. package/lib/types/task-auth.d.ts +9 -0
  103. package/lib/types/task-ledger-rows.d.ts +21 -4
  104. package/lib/types/task-ledger.d.ts +9 -0
  105. package/lib/types/types.d.ts +7 -4
  106. package/nexus-stage/scripts/mockhost.py +2 -2
  107. package/nexus-stage/src/main.ts +27 -0
  108. package/nexus-stage/src/planning-card-text.ts +1 -1
  109. package/nexus-stage/src/planning-team-roles.ts +80 -0
  110. package/nexus-stage/src/planning-types.ts +2 -0
  111. package/nexus-stage/src/planning-view.ts +1 -0
  112. package/nexus-stage/src/planning.css +29 -9
  113. package/nexus-stage/src/wb-superagent.ts +518 -0
  114. package/nexus-stage/src/workbench.css +32 -0
  115. package/nexus-stage/src/workbench.ts +25 -3
  116. package/nexus-stage/src/world.ts +1 -1
  117. package/package.json +8 -2
  118. package/assets/nexusDist/assets/index-C7HagaGy.css +0 -1
  119. package/assets/nexusDist/assets/index-CA_YZTWG.js +0 -9
  120. package/assets/stageDist/assets/index-Bj7S2pA1.css +0 -1
  121. package/assets/stageDist/assets/index-C-28k_o5.js +0 -974
  122. package/assets/stageDist/assets/interiors-CQGBjffT.png +0 -0
  123. package/assets/stageDist/assets/office-tileset-CHQT-uYL.png +0 -0
  124. package/assets/stageDist/index.html +0 -13
  125. package/lib/legacy/teams-bridge-inbound.js +0 -156
  126. package/lib/teams-bridge.js +0 -18
  127. package/lib/types/legacy/teams-bridge-inbound.d.ts +0 -94
  128. package/lib/types/teams-bridge.d.ts +0 -112
@@ -0,0 +1,61 @@
1
+ import { type Decision, type OutboundMessage, type ReplyStatus, type Repositories, type Thread, type Ticket, type Trigger, type TriggerDisposition } from '../upstream/dsh-superagent/src/core/index.ts';
2
+ /** One queued Channel message and what became of it. */
3
+ export interface StoredMessage {
4
+ readonly message: OutboundMessage;
5
+ status: ReplyStatus;
6
+ readonly queuedAt: string;
7
+ sentAt?: string;
8
+ droppedAt?: string;
9
+ reason?: string;
10
+ }
11
+ export declare class JsonRepositories implements Repositories {
12
+ private readonly path;
13
+ private triggerRows;
14
+ private dispositionRows;
15
+ private threadRows;
16
+ private ticketRows;
17
+ private decisionRows;
18
+ private outboxRows;
19
+ private depth;
20
+ /** Why the file could not be loaded; the store then refuses every write rather than overwrite what it could not read. */
21
+ readonly loadError: string | undefined;
22
+ /** @param path - the JSON document; '' keeps the store in memory (tests). */
23
+ constructor(path: string);
24
+ private maps;
25
+ private load;
26
+ private persist;
27
+ /** A unit of work: rolled back in memory when it throws, written to disk once the outermost one succeeds. */
28
+ atomic<T>(work: () => T): T;
29
+ readonly triggers: {
30
+ get: (id: string) => Trigger | undefined;
31
+ save: (trigger: Trigger) => void;
32
+ disposition: (id: string) => TriggerDisposition | undefined;
33
+ saveDisposition: (id: string, value: TriggerDisposition) => void;
34
+ };
35
+ readonly threads: {
36
+ get: (key: string) => Thread | undefined;
37
+ save: (thread: Thread) => void;
38
+ list: () => Thread[];
39
+ active: () => Thread[];
40
+ };
41
+ readonly tickets: {
42
+ get: (id: string) => Ticket | undefined;
43
+ save: (ticket: Ticket) => void;
44
+ /** Newest first, as upstream's stores order them. */
45
+ list: () => Ticket[];
46
+ open: () => Ticket[];
47
+ active: () => Ticket[];
48
+ };
49
+ readonly decisions: {
50
+ get: (id: string) => Decision | undefined;
51
+ save: (decision: Decision) => void;
52
+ byThread: (key: string) => Decision[];
53
+ list: () => Decision[];
54
+ };
55
+ /** The Outbox's rows (not part of the engine's Repositories port). */
56
+ readonly messages: {
57
+ get: (id: string) => StoredMessage | undefined;
58
+ save: (row: StoredMessage) => void;
59
+ list: () => StoredMessage[];
60
+ };
61
+ }
@@ -0,0 +1,32 @@
1
+ import type { Context } from '@deepseek-ai/cordis';
2
+ import type { SuperagentHost } from './index.ts';
3
+ type JsonValue = null | boolean | number | string | JsonValue[] | {
4
+ [key: string]: JsonValue;
5
+ };
6
+ interface RouteItem {
7
+ trigger_id?: unknown;
8
+ kind?: unknown;
9
+ title?: unknown;
10
+ scope?: unknown;
11
+ reason?: unknown;
12
+ acknowledgement?: unknown;
13
+ ticket_id?: unknown;
14
+ name?: unknown;
15
+ note?: unknown;
16
+ rules?: unknown;
17
+ repo?: unknown;
18
+ }
19
+ /** One routing item, decided on its own: a refused item never stops the others (upstream docs/002). */
20
+ export declare function routeItem(host: SuperagentHost, item: RouteItem): Record<string, JsonValue>;
21
+ /**
22
+ * The text an attention reply sends: the router's words, led by the member's question verbatim when they do not already
23
+ * contain it — the engine checks the question against the ticket's open one, but only the text reaches the person.
24
+ * @param text - what the router wrote.
25
+ * @param question - the ticket's open question, copied exactly.
26
+ * @returns the text to send.
27
+ */
28
+ export declare function attentionText(text: string, question: string): string;
29
+ /** The most a superagent tool result shows the model, in characters of its JSON. */
30
+ export declare const SAID_CAP = 12000;
31
+ export declare function registerSuperagentTools(ctx: Context, host: () => SuperagentHost | undefined): void;
32
+ export {};
@@ -0,0 +1,218 @@
1
+ export interface Localized {
2
+ zh: string;
3
+ en: string;
4
+ }
5
+ export interface ThreadRef {
6
+ source: string;
7
+ id: string;
8
+ }
9
+ export interface ChannelRef {
10
+ source: string;
11
+ thread: string;
12
+ address: Record<string, string>;
13
+ }
14
+ /** One message of the mailbox as superagent takes it in; `text` and `meta` are untrusted data. */
15
+ export interface Trigger {
16
+ id: string;
17
+ source: string;
18
+ threads: ThreadRef[];
19
+ actor: {
20
+ source: string;
21
+ id: string;
22
+ };
23
+ human: boolean;
24
+ addressed?: 'mention' | 'direct';
25
+ at: string;
26
+ text: string;
27
+ channel?: ChannelRef;
28
+ url?: string;
29
+ meta: Record<string, unknown>;
30
+ }
31
+ export type ScopeResult = {
32
+ listened: true;
33
+ observed: boolean;
34
+ row?: string;
35
+ } | {
36
+ listened: false;
37
+ reason: string;
38
+ };
39
+ export interface OutboundMessage {
40
+ id: string;
41
+ channel: ChannelRef;
42
+ text: string;
43
+ kind: 'acknowledgement' | 'reply' | 'notice';
44
+ ticketId?: string;
45
+ }
46
+ export type ReceiveResult = 'stored' | 'duplicate' | 'filtered';
47
+ export interface Commands {
48
+ withSignal(signal?: AbortSignal): Commands;
49
+ run(program: string, args: string[], cwd?: string): Promise<string>;
50
+ }
51
+ /** Only the codes the a2a Source reports with. */
52
+ export type HealthCode = 'setupPending' | 'sourceOff' | 'pollFailures';
53
+ export interface Health {
54
+ state: 'starting' | 'ready' | 'paused' | 'error';
55
+ detail: string;
56
+ at?: string;
57
+ code?: HealthCode;
58
+ values?: Record<string, string>;
59
+ }
60
+ export interface SchemaLike<T> {
61
+ parse(value: unknown): T;
62
+ safeParse(value: unknown): {
63
+ success: true;
64
+ data: T;
65
+ } | {
66
+ success: false;
67
+ };
68
+ }
69
+ export type FieldSpec = {
70
+ key: string;
71
+ label: Localized;
72
+ advanced?: true;
73
+ type: 'number';
74
+ min: number;
75
+ max: number;
76
+ } | {
77
+ key: string;
78
+ label: Localized;
79
+ advanced?: true;
80
+ type: 'select';
81
+ options: {
82
+ value: string;
83
+ label: Localized;
84
+ }[];
85
+ } | {
86
+ key: string;
87
+ label: Localized;
88
+ type: 'rows';
89
+ columns: {
90
+ key: string;
91
+ label: Localized;
92
+ type: 'text';
93
+ optional?: boolean;
94
+ }[];
95
+ };
96
+ export interface ContextMessage {
97
+ id: string;
98
+ from: string;
99
+ at: string;
100
+ text: string;
101
+ bot?: true;
102
+ }
103
+ export interface ContextPart {
104
+ messages: ContextMessage[];
105
+ next?: string;
106
+ body: Record<string, unknown>;
107
+ }
108
+ /** How a ticket ended (upstream TicketOutcome / TicketEndBy); the a2a Source maps it to a receipt outcome (p3 design P3-6). */
109
+ export type TicketOutcome = 'completed' | 'merged' | 'closed' | 'dropped' | 'stopped';
110
+ export type TicketEndBy = 'executor' | 'human';
111
+ /** The part of a ticket the a2a Source reads: whether and how it ended. */
112
+ export interface TicketView {
113
+ id: string;
114
+ ended?: {
115
+ at: string;
116
+ by: TicketEndBy;
117
+ outcome: TicketOutcome;
118
+ reason?: string;
119
+ };
120
+ /** The ticket's open question for a person; its reply's message id is key('attention-reply', attention.id). */
121
+ attention?: {
122
+ id: string;
123
+ };
124
+ }
125
+ /** What the a2a Source uses of the context superagent hands a Source plugin. */
126
+ export interface SourceContext {
127
+ readonly commands: Commands;
128
+ readonly ready: Promise<void>;
129
+ configured(): boolean;
130
+ config<C extends Record<string, unknown>>(kind: string): C | undefined;
131
+ receive(trigger: Trigger): ReceiveResult | Promise<ReceiveResult>;
132
+ state: {
133
+ get<V>(key: string): V | undefined;
134
+ set<V>(key: string, value: V | undefined): void;
135
+ };
136
+ threads: {
137
+ describe(key: string, description: {
138
+ label?: string;
139
+ url?: string;
140
+ }): void;
141
+ };
142
+ tickets: {
143
+ get(id: string): TicketView | undefined;
144
+ };
145
+ report(entry: string, health: Health): void;
146
+ }
147
+ /** What the a2a Source uses of superagent's host service (`orchestrator`). */
148
+ export interface SourceHost {
149
+ readonly sources: {
150
+ register<C extends Record<string, unknown>>(kind: SourceKind<C>): () => void;
151
+ };
152
+ context(kind: {
153
+ kind: string;
154
+ health: readonly string[];
155
+ }): SourceContext;
156
+ }
157
+ /** The kind descriptor the a2a Source registers. */
158
+ export interface SourceKind<C extends Record<string, unknown>> {
159
+ kind: string;
160
+ title: Localized;
161
+ description: Localized;
162
+ schema: SchemaLike<C>;
163
+ fields: FieldSpec[];
164
+ health: string[];
165
+ scope(input: {
166
+ meta: Record<string, unknown>;
167
+ }, config: C): ScopeResult;
168
+ channel: {
169
+ allowed(address: Record<string, string>, config: C): boolean;
170
+ send(host: {
171
+ commands: Commands;
172
+ }, message: OutboundMessage): Promise<'sent' | 'gone'>;
173
+ link(address: Record<string, string>, links: unknown): {
174
+ url: string;
175
+ label: Localized;
176
+ };
177
+ };
178
+ threadContext: {
179
+ messageId(trigger: Trigger): string;
180
+ read(commands: Commands, trigger: Trigger, part: 'thread' | 'root' | 'parent', cursor: string | undefined, config: C): Promise<ContextPart>;
181
+ };
182
+ policy: {
183
+ schema: SchemaLike<Record<string, unknown> & {
184
+ allowed: {
185
+ id: string;
186
+ name?: string;
187
+ }[];
188
+ }>;
189
+ fields: FieldSpec[];
190
+ explicit: Localized;
191
+ rows(config: Record<string, unknown>): {
192
+ id: string;
193
+ label: string;
194
+ note: Localized;
195
+ cells: {
196
+ listedUnaddressed: boolean;
197
+ unlistedAddressed: boolean;
198
+ unlistedUnaddressed: boolean;
199
+ };
200
+ }[];
201
+ };
202
+ environment: {
203
+ variables: readonly {
204
+ key: string;
205
+ description: Localized;
206
+ }[];
207
+ values(input: {
208
+ config: C;
209
+ trigger?: Trigger;
210
+ }): Record<string, string>;
211
+ };
212
+ }
213
+ /** superagent's content-derived id: the same inputs always give the same 32-hex id (contract-checked against upstream). */
214
+ export declare function key(...values: string[]): string;
215
+ /** superagent's Thread key, `<source>:<id>`. */
216
+ export declare const threadKey: (ref: ThreadRef) => string;
217
+ /** superagent's fixed health entry for `code`; the panel localizes it by code. */
218
+ export declare function health(state: Health['state'], code: HealthCode, values?: Record<string, string>): Health;
@@ -0,0 +1,53 @@
1
+ import type { ReportState, Ticket } from './model.ts';
2
+ import { EnginePart, type EngineOptions } from './part.ts';
3
+ import type { Replies } from './replies.ts';
4
+ import { type Tickets } from './tickets.ts';
5
+ /** What an Assignment reports: a worker's report, or the Executor's own (`waiting` after an idle turn, `failed` after an error). */
6
+ export interface WorkerReport {
7
+ state: ReportState;
8
+ summary: string;
9
+ /** Open question for a person: a string asks it, `null` clears an open one, and `undefined` keeps the current one. */
10
+ question?: string | null;
11
+ /** The person's message whose request raised the question; routes the question to the channel where it was written. */
12
+ askedBy?: string;
13
+ /** The person's question this report answers, which the worker thereby takes up; authorizes the main Session to send an answer reply. */
14
+ answers?: string;
15
+ }
16
+ /**
17
+ * Assignments records what the Executor and its workers report about the Assignments that run tickets: one started, Inputs
18
+ * reached it or failed to, its worker's Session took Inputs into a step, a turn of its worker ended, a host restart
19
+ * interrupted it, and a worker's report with its question for a person. It depends on
20
+ * Tickets to restart or end a ticket and on Replies to withdraw a question a report replaced; the Engine routes the
21
+ * Executor's lifecycle callbacks and its workers' reports here.
22
+ */
23
+ export declare class Assignments extends EnginePart {
24
+ private readonly tickets;
25
+ private readonly replies;
26
+ constructor(options: EngineOptions, tickets: Tickets, replies: Replies);
27
+ /** Marks a non-ended assignment running, queues delivery of waiting undelivered inputs on an open ticket, and emits `assignment.started`. */
28
+ started(ticketId: string, assignmentId: string): void;
29
+ /**
30
+ * Marks `inputIds` delivered on the ticket's running assignment and clears any prior `delivery` failure; ignored if no
31
+ * longer running. Its worker reads each once its Session takes it into a step (see `read`).
32
+ */
33
+ delivered(ticketId: string, assignmentId: string, inputIds: string[]): void;
34
+ /** Records when the worker's Session of an open ticket took `inputIds` into a step, from which its model reads them. */
35
+ read(ticketId: string, inputIds: string[]): void;
36
+ turnEnded(ticketId: string, assignmentId: string): void;
37
+ deliveryFailed(ticketId: string, assignmentId: string, error: string): void;
38
+ /**
39
+ * Handles a running assignment interrupted by a host restart: restarts it with a recovery note unless its latest report is
40
+ * `waiting`, `ready`, `blocked`, or `failed` and no input was delivered after that report, in which case it keeps its
41
+ * session and flushes any waiting undelivered inputs.
42
+ */
43
+ interrupted(ticketId: string, assignmentId: string): void;
44
+ /**
45
+ * Records a worker status report on an open ticket's current assignment, updating `attention`, `answers`, held automated
46
+ * inputs, and ending the ticket when `dropped` or when `ready` and not waiting on followed threads (`followsDone`).
47
+ * @throws UserError for an unknown or ended ticket, an ended assignment, a question combined with a ready result or answer,
48
+ * or a question/answer referencing a non-human or unreached trigger.
49
+ */
50
+ report(ticketId: string, report: WorkerReport): Ticket;
51
+ /** The ticket, while it is open and `assignmentId` runs it. */
52
+ private running;
53
+ }
@@ -0,0 +1,191 @@
1
+ import type { Decision, PolicyEffect, ThreadRef, Ticket, Trigger } from './model.ts';
2
+ import type { Candidate } from './ports.ts';
3
+ import type { EngineOptions } from './part.ts';
4
+ import { type WorkerReport } from './assignments.ts';
5
+ import { type Outcome } from './evals.ts';
6
+ import { type ReceiveResult } from './intake.ts';
7
+ import { type Reply, type ReplyRequest } from './replies.ts';
8
+ export type { EngineOptions } from './part.ts';
9
+ export type { WorkerReport } from './assignments.ts';
10
+ export type { Outcome } from './evals.ts';
11
+ export type { ReceiveResult } from './intake.ts';
12
+ export type { Reply, ReplyRequest } from './replies.ts';
13
+ /**
14
+ * Single transactional entry point for mutating Triggers, Threads, Decisions, Tickets, and Assignments.
15
+ * Coordinates Intake, Evals, Tickets, Assignments, and Replies inside synchronous repository transactions while queuing side
16
+ * effects through ports. Callers receive role-scoped `Pick` interfaces rather than the full engine.
17
+ */
18
+ export declare class Engine {
19
+ private readonly options;
20
+ private readonly repo;
21
+ private readonly replies;
22
+ private readonly tickets;
23
+ private readonly assignments;
24
+ private readonly evals;
25
+ private readonly intake;
26
+ constructor(options: EngineOptions);
27
+ /**
28
+ * A Source's request to take in a Trigger: store it once, fan it out to the tickets that subscribe to its Threads (to an
29
+ * ended one only a person's message, which resumes it at once unless processing is paused, and to none a person stopped),
30
+ * and queue it for Eval on its primary Thread unless a ticket's worker decides it (see `followupOwners`).
31
+ * Triggers that arrive while an Eval of that Thread runs wait together for the next one.
32
+ */
33
+ receive(trigger: Trigger): ReceiveResult;
34
+ /**
35
+ * A Source's request to make an open ticket follow one of its Threads, such as a pull request's, `own` when the ticket
36
+ * opened it: the ticket subscribes to it, and a ready report ends it only once `followsDone` holds (see `Tickets.followsDone`).
37
+ * @throws UserError when the ticket is unknown or has ended.
38
+ */
39
+ bindThread(ticketId: string, thread: ThreadRef, own: boolean): Ticket;
40
+ /**
41
+ * A Source's fact that a Thread closed, such as its pull request's merge, at the time it happened. An open ticket that
42
+ * follows it ends once it is done with the Threads it follows, unless work resumed since the close has not finished, or
43
+ * its worker took up a person's message the ticket decides after its latest report.
44
+ */
45
+ threadClosed(thread: ThreadRef, outcome: 'merged' | 'closed', at: string): void;
46
+ /**
47
+ * Requeues overdue Evals up to `REQUEUES` times before recording `unavailable` (undelivered Evals never expire), starts the
48
+ * Evals of Threads whose queued Triggers wait, and resumes ended tickets a person's message reached while processing was
49
+ * paused. While processing is paused, nothing expires: each Eval in progress notes when the pause began, and its deadline
50
+ * moves forward by the pause's length once processing resumes. Each Eval and each ticket update takes one transaction.
51
+ */
52
+ evaluateDue(): void;
53
+ /** The candidate of the Eval that holds a Trigger, as its assessor sees it; undefined while no Eval holds it. */
54
+ candidate(triggerId: string): Candidate | undefined;
55
+ /**
56
+ * Decide a Trigger: the Eval that holds it, or a direct Eval of it alone when none does, such as a person's explicit
57
+ * request the main Session routes. A proactive candidate is accepted only in `auto` mode with enabled rules its assessment
58
+ * matched, and a Trigger that already started a ticket returns that ticket's Decision. An invalid stop is recorded as
59
+ * `ignore`; one judged under an older Policy as `unavailable`.
60
+ * @throws UserError when the Trigger is unknown or not admissible, `outcome.evalId` names an Eval that has finished, a
61
+ * ticket's worker still decides the Trigger and the outcome is not a stop, or an inferred candidate is accepted outside `auto`
62
+ * mode or without enabled matching rules.
63
+ */
64
+ decide(triggerId: string, outcome: Outcome): Decision;
65
+ /**
66
+ * Attach a Trigger to a ticket that the message points at: the ticket follows the Trigger's Threads and receives it as an
67
+ * Input with the routing note, and the Eval that holds the Trigger ends, since the ticket has it now; the other Triggers of
68
+ * its batch wait for a fresh Eval. A note for an Input the worker already received goes out as a new Input, and so does a
69
+ * message the ticket let go, read for context only, or had before it ended. An ended ticket resumes under its Mandate, at
70
+ * once unless processing is paused.
71
+ * @throws UserError for a ticket a person stopped, which withdrew its Mandate, or one whose Mandate the Policy no longer holds.
72
+ */
73
+ attach(ticketId: string, triggerId: string, note?: string): Ticket;
74
+ /**
75
+ * Ask a running worker that waits in `waiting` state for its status; any other worker is left alone.
76
+ * @returns whether the worker was asked.
77
+ * @throws UserError when the ticket is unknown.
78
+ */
79
+ requestStatus(ticketId: string): boolean;
80
+ /**
81
+ * Queue a message for the Channel its purpose names: an acknowledgement or an answer goes where the person's message was
82
+ * written, attention where the message that raised the question was, else, like a result, to the conversation the ticket
83
+ * started in. A message queued before is not queued again (see `Replies.reply`).
84
+ * @throws UserError when the ticket or trigger is unknown or the purpose's rule refuses it, such as a result of a ticket that
85
+ * is not ready, completed, merged, or dropped.
86
+ */
87
+ reply(request: ReplyRequest): Reply;
88
+ /** The assessor delivered an Eval's candidate to its Session: the Eval's deadline counts from now. */
89
+ candidateDelivered(evalId: string): void;
90
+ /**
91
+ * Queue a stored Trigger for a fresh Eval, such as a person's replay; returns false while an Eval holds it.
92
+ * @throws UserError when the trigger is unknown.
93
+ */
94
+ reevaluate(triggerId: string): boolean;
95
+ /**
96
+ * A person dismisses the problem an unavailable Decision shows: the overview lists it no more.
97
+ * @throws UserError for a Decision that is unknown or not unavailable.
98
+ */
99
+ dismiss(decisionId: string): Decision;
100
+ /**
101
+ * Drop every ticket's Subscription to a Thread, until a new Decision subscribes one again.
102
+ * @returns whether a Subscription was dropped.
103
+ */
104
+ unsubscribe(thread: string): boolean;
105
+ /**
106
+ * A person stops a ticket, which withdraws its Mandate: it ends and receives nothing more.
107
+ * @throws UserError when the ticket is unknown.
108
+ */
109
+ stopTicket(ticketId: string, reason?: string): Ticket;
110
+ /**
111
+ * A person retries a ticket whose worker reported failed or blocked (or whose input delivery failed): the stalled
112
+ * Assignment ends and a new one starts under the same Mandate.
113
+ * @throws UserError when the ticket is unknown, has ended, or is not retryable.
114
+ */
115
+ retryTicket(ticketId: string): Ticket;
116
+ /**
117
+ * The Executor's fact that an Assignment runs; the Inputs that wait for it go out.
118
+ * @throws UserError when the ticket is unknown.
119
+ */
120
+ assignmentStarted(ticketId: string, assignmentId: string): void;
121
+ /**
122
+ * The Executor's fact that Inputs reached the Assignment that runs the ticket, which clears a failed delivery. A fact about
123
+ * an Assignment that no longer runs is dropped. Its worker reads each once its Session takes it into a step (`inputsRead`).
124
+ */
125
+ inputsDelivered(ticketId: string, assignmentId: string, inputIds: string[]): void;
126
+ /**
127
+ * The Executor's fact that the worker's Session of an open ticket took the messages that carried Inputs into a step, from
128
+ * which its model reads them: a report or the end of a turn after that counts them as read at the ticket's end.
129
+ * @throws UserError when the ticket is unknown.
130
+ */
131
+ inputsRead(ticketId: string, inputIds: string[]): void;
132
+ /** The Executor's fact that a turn of the worker of the Assignment that runs the ticket ended, after a report too. */
133
+ turnEnded(ticketId: string, assignmentId: string): void;
134
+ /** The Executor's fact that delivering Inputs to the Assignment that runs the ticket failed; the ticket shows it until a delivery succeeds. */
135
+ deliveryFailed(ticketId: string, assignmentId: string, error: string): void;
136
+ /**
137
+ * A worker's request, through its Executor, to mark a Thread attached to its ticket unrelated, for `reason`: only that
138
+ * ticket's Subscription drops, until a new Decision subscribes it again.
139
+ * @throws UserError when the ticket is unknown, or for the Thread the ticket started on, one a Source bound it to (such as
140
+ * its pull request's), or one it does not follow.
141
+ */
142
+ markUnrelated(ticketId: string, thread: string, reason: string): void;
143
+ /**
144
+ * An Executor's Subscription to a Thread it found related, for context: see `Tickets.followForContext` and `Thread.context`.
145
+ * @returns false when the ticket already follows the Thread.
146
+ * @throws UserError when the ticket is unknown or has ended.
147
+ */
148
+ followForContext(ticketId: string, thread: ThreadRef): boolean;
149
+ /**
150
+ * A fact the main Session gives an open ticket's Executor: see `Tickets.note`.
151
+ * @throws UserError when the ticket is unknown or has ended.
152
+ */
153
+ note(ticketId: string, text: string): Ticket;
154
+ /**
155
+ * An Executor's hand-back of a message that reached its ticket but asks for more than it: see `Evals.handback`.
156
+ * @returns whether it was queued for Eval: false while another ticket still decides it, and for one this ticket did not decide (see `Evals.handback`).
157
+ * @throws UserError when the ticket or trigger is unknown, the trigger did not reach the ticket, or the ticket already handed it back.
158
+ */
159
+ handback(ticketId: string, triggerId: string, reason: string): boolean;
160
+ /**
161
+ * Record a report on an open ticket's current Assignment. Its question for a person (`attention`) is asked, kept, or
162
+ * cleared (`null` or a `ready` report), and a replaced attention question whose reply has not been sent yet is withdrawn
163
+ * from the outbox. A `blocked` or `failed` report holds back automated inputs until a human message arrives. A `dropped`
164
+ * report ends the ticket, and a `ready` report ends it: `completed` without followed Threads, else with the `followsDone`
165
+ * outcome once `followsDone` holds.
166
+ * @throws UserError for an unknown or ended ticket, an ended assignment, a question that comes with a ready result or an
167
+ * answer, or a question or answer that names a message that is not a person's or did not reach the ticket.
168
+ */
169
+ report(ticketId: string, report: WorkerReport): Ticket;
170
+ /**
171
+ * Handles an assignment that was running when the host stopped: restarts it with a recovery note unless its latest report is
172
+ * `waiting`, `ready`, `blocked`, or `failed` and no Input reached its worker after that report, in which case it keeps its
173
+ * Session and state and gets the Inputs that wait for it.
174
+ */
175
+ assignmentInterrupted(ticketId: string, assignmentId: string): void;
176
+ /**
177
+ * The Policy changed: each open ticket in `effects` is told how the change bears on it, and Evals in progress start again
178
+ * under the new version.
179
+ */
180
+ policyChanged(from: string, to: string, effects?: ReadonlyMap<string, PolicyEffect>): void;
181
+ }
182
+ /** What Sources ask and tell the Engine. */
183
+ export type EngineForSources = Pick<Engine, 'receive' | 'bindThread' | 'threadClosed'>;
184
+ /** What the main Session asks of the Engine. */
185
+ export type EngineForMainSession = Pick<Engine, 'candidate' | 'candidateDelivered' | 'decide' | 'attach' | 'reply' | 'requestStatus' | 'note'>;
186
+ /** What people ask of the Engine, through the panel or the main Session. */
187
+ export type EngineForPeople = Pick<Engine, 'stopTicket' | 'retryTicket' | 'reevaluate' | 'unsubscribe' | 'dismiss'>;
188
+ /** What Settings tells the Engine. */
189
+ export type EngineForSettings = Pick<Engine, 'policyChanged'>;
190
+ /** What the Executor tells the Engine, and what its workers ask of it. */
191
+ export type EngineForExecutor = Pick<Engine, 'assignmentStarted' | 'inputsDelivered' | 'inputsRead' | 'turnEnded' | 'deliveryFailed' | 'assignmentInterrupted' | 'report' | 'markUnrelated' | 'handback' | 'followForContext' | 'reply'>;
@@ -0,0 +1,58 @@
1
+ /** User-facing error codes mapped to their category ('missing' or 'refused') and English message template. */
2
+ export declare const USER_ERRORS: {
3
+ readonly unknownTicket: readonly ["missing", "Unknown ticket"];
4
+ readonly unknownProblem: readonly ["missing", "Unavailable Eval not found"];
5
+ readonly unknownTrigger: readonly ["missing", "Unknown trigger"];
6
+ readonly unknownAssignment: readonly ["missing", "Unknown assignment"];
7
+ readonly unknownBlock: readonly ["missing", "Unknown settings block: {block}"];
8
+ readonly unknownPromptRevision: readonly ["missing", "Unknown prompt revision {revision}"];
9
+ readonly unknownPromptPart: readonly ["refused", "Unknown built-in prompt part {part}"];
10
+ readonly ticketEnded: readonly ["refused", "Ticket has ended"];
11
+ readonly assignmentEnded: readonly ["refused", "Assignment has ended; a newer assignment owns this ticket"];
12
+ readonly evalFinished: readonly ["refused", "Eval {eval} has finished or a later eval replaced it; decide the trigger's current eval"];
13
+ readonly notAdmissible: readonly ["refused", "Trigger is not admissible: {reason}"];
14
+ readonly notExplicit: readonly ["refused", "An accept through orchestrator_route is for explicit requests from allowed senders; assess proactive candidates with orchestrator_eval and orchestrator_eval_decide"];
15
+ readonly ticketStopped: readonly ["refused", "A person stopped this ticket; new work needs an accept through orchestrator_route"];
16
+ readonly mandateRevoked: readonly ["refused", "The current policy no longer holds this ticket's mandate; new work needs an accept through orchestrator_route"];
17
+ readonly notRetryable: readonly ["refused", "Only an open ticket can be retried, and only when its worker last reported failed or blocked and no person has sent a message since, or when delivering an Input to its worker failed"];
18
+ readonly sourceThread: readonly ["refused", "This is the thread the ticket started on; it stays subscribed"];
19
+ readonly followedThread: readonly ["refused", "This thread is the ticket's own, such as its pull request's; it stays subscribed"];
20
+ readonly notFollowing: readonly ["refused", "This ticket does not follow that thread"];
21
+ readonly questionWithResult: readonly ["refused", "A question for a person cannot also be a ready result or an answer; report it separately"];
22
+ readonly askerWithoutQuestion: readonly ["refused", "The message that raised a question needs the question it raised"];
23
+ readonly notAsker: readonly ["refused", "A question must name the person's message that raised it, which reached this ticket"];
24
+ readonly notAnswerable: readonly ["refused", "An answer must name the person's question it answers, which reached this ticket"];
25
+ readonly ackEnded: readonly ["refused", "Ticket ended; do not acknowledge historical requests"];
26
+ readonly notReached: readonly ["refused", "Trigger does not belong to this worker"];
27
+ readonly handedBack: readonly ["refused", "This ticket handed that trigger back already"];
28
+ readonly handedBackHere: readonly ["refused", "The worker of this ticket handed that trigger back as beyond it: accept it as new work, attach it to another ticket, or ignore it"];
29
+ readonly workerDecides: readonly ["refused", "This message reached ticket {tickets} on its thread: its worker decides whether it belongs there and hands back what does not, which then arrives as a candidate. Only a stop goes through orchestrator_route, with kind stop"];
30
+ readonly ackNoChannel: readonly ["refused", "Acknowledgement requires an assigned human source message"];
31
+ readonly ackNotPerson: readonly ["refused", "Use the original human trigger, not a bot, CI or worker report"];
32
+ readonly notReady: readonly ["refused", "Ticket is not ready for delivery. Keep progress internal and wait for a verified ready report; do not relabel progress as an answer or send it through another channel."];
33
+ readonly notAttention: readonly ["refused", "Attention requires the ticket's current attention question in human_action. Routine unfinished work stays internal."];
34
+ readonly notQuestion: readonly ["refused", "An answer must target the original human question, not a worker report or automated trigger"];
35
+ readonly noAnswer: readonly ["refused", "No worker answer is ready for this human trigger. Wait for the worker's report, or request one with orchestrator_ticket_request_status, which acts only on a worker that reported waiting; ordinary progress cannot be relabelled as an answer."];
36
+ readonly noChannel: readonly ["refused", "No reply channel for this ticket or trigger"];
37
+ readonly panelOnlyEnvironment: readonly ["refused", "The execution environment (ticket directory, prepare command, blocked commands) can only be changed in the management panel"];
38
+ readonly panelOnlyAccounts: readonly ["refused", "Source fields that setup reads, such as account CLIs, can only be changed in the management panel"];
39
+ readonly setupComplete: readonly ["refused", "Setup is complete"];
40
+ readonly modelUnavailable: readonly ["refused", "The {block} model is not available: {error}"];
41
+ readonly promptTooLong: readonly ["refused", "Prompt configuration exceeds {limit} characters"];
42
+ readonly promptPlaceholders: readonly ["refused", "The “{part}” template must keep {placeholders}, which the system fills in"];
43
+ readonly promptPartEmpty: readonly ["refused", "The “{part}” part cannot be empty; reset it to follow its built-in text"];
44
+ readonly sourceNotInstalled: readonly ["refused", "The {source} Source kind is not installed"];
45
+ readonly noLabels: readonly ["refused", "This Source has no names to refresh"];
46
+ readonly nothingToSync: readonly ["refused", "The {source} Source's part of the Policy has nothing to sync from, or the Source is off or waiting for setup"];
47
+ };
48
+ export type UserErrorCode = keyof typeof USER_ERRORS;
49
+ /**
50
+ * Structured error thrown by Engine parts and application services when a caller request is invalid or references missing state.
51
+ * Tool handlers and HTTP routes inspect its code and missing flag to return appropriate status responses, while the web panel localizes the code.
52
+ */
53
+ export declare class UserError extends Error {
54
+ readonly code: UserErrorCode;
55
+ readonly values: Record<string, string>;
56
+ readonly missing: boolean;
57
+ constructor(code: UserErrorCode, values?: Record<string, string>);
58
+ }