@ziggs-ai/contracts 0.34.0 → 0.43.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/dist/inbox.d.ts CHANGED
@@ -54,6 +54,11 @@ export interface DecisionRef {
54
54
  * the request the agent actually filed — nothing here is inferred.
55
55
  */
56
56
  access?: AccessAsk;
57
+ /** An approved permission may still need its grant applied. Retrying does not ask for consent again. */
58
+ permissionChange?: {
59
+ consent: 'pending' | 'approved' | 'rejected';
60
+ fulfillment: 'pending' | 'applied' | 'failed';
61
+ };
57
62
  }
58
63
  /**
59
64
  * What an access ask is asking for, as the person answering needs to read it.
@@ -128,8 +133,17 @@ export interface InboxDeliveryRef {
128
133
  resourceId: string;
129
134
  /** One emit, one id — collapse copies of the same event on this. */
130
135
  eventId: string;
131
- /** Explicit assignment identity; use this for acknowledgement when present. */
132
- responsibilityId?: string;
136
+ /** Canonical work identity, separate from this delivery's acknowledgment. */
137
+ action?: import('./actions').ActionRef;
138
+ /** Task disposition read from its owner; never a second lifecycle. */
139
+ actionState?: 'ready' | 'waiting' | 'settled';
140
+ actionVersion?: string;
141
+ input?: {
142
+ kind: 'artifact';
143
+ id: string;
144
+ };
145
+ /** Exact receipt identity; acknowledgment never completes the action. */
146
+ receiptId?: string;
133
147
  executionContext?: import('./execution').WorkExecutionContext;
134
148
  executionBlocked?: import('./execution').ExecutionBlock;
135
149
  /** The mailbox this copy lives in. */
@@ -139,7 +153,7 @@ export interface InboxDeliveryRef {
139
153
  assigneeId: string | null;
140
154
  /** The owner's human should see this. */
141
155
  needsHuman: boolean;
142
- chatId: string | null;
156
+ addressId: string | null;
143
157
  agreementId: string | null;
144
158
  taskId: string | null;
145
159
  /** ISO instant of the event; the axis `ackTo` moves along. */
@@ -172,7 +186,7 @@ export interface InboxDeliveryRef {
172
186
  * read. `remedy` says in one line what would put it in reach.
173
187
  */
174
188
  outOfReach?: {
175
- scopeKind: 'chat' | 'agreement' | 'task' | 'artifact';
189
+ scopeKind: 'message' | 'address' | 'agreement' | 'task' | 'artifact';
176
190
  scopeId: string;
177
191
  remedy: string;
178
192
  } | null;
@@ -213,6 +227,16 @@ export type AttentionEntry = {
213
227
  at: string;
214
228
  source: 'notice';
215
229
  notice: InboxDeliveryRef;
230
+ }
231
+ /** A question someone asked this person to answer, still pending. The message owns the slot. */
232
+ | {
233
+ key: string;
234
+ at: string;
235
+ source: 'answer';
236
+ answer: {
237
+ messageId: string;
238
+ requestId: string;
239
+ };
216
240
  };
217
241
  /** How many notice rows one attention window can carry. */
218
242
  export declare const INBOX_ATTENTION_NOTICE_CAP = 50;
@@ -232,12 +256,14 @@ export declare const INBOX_ATTENTION_NOTICE_CAP = 50;
232
256
  */
233
257
  export interface AttentionFeed {
234
258
  asOf: string;
235
- /** Decisions first — somebody is blocked on those — then notices, newest first. */
259
+ /** Decisions first — somebody is blocked on those — then questions to answer, then notices, newest first. */
236
260
  items: AttentionEntry[];
237
261
  /** Decisions the server capped. Nothing local can expand into them. */
238
262
  truncated: number;
239
263
  /** Older unseen notice rows exist past the cap; they stay unseen. */
240
264
  hasMore: boolean;
265
+ /** Older readable pending questions. Pass verbatim as answerBefore to GET /inbox/attention. */
266
+ answerNextCursor: string | null;
241
267
  /**
242
268
  * Opaque token for `POST /inbox/seen`, covering the notice rows above and
243
269
  * nothing else. Null when the block carried no notices. Never constructed
@@ -256,7 +282,7 @@ export interface MarkInboxSeenBody {
256
282
  }
257
283
  /** Marketplace request triage channel shared by the server and hosted clients. */
258
284
  export interface InboxOpenRequestRef {
259
- responsibilityId: string;
285
+ receiptId: string;
260
286
  agreementId: string;
261
287
  /** Exact-match triage string from the publisher (`metadata.match`). */
262
288
  match: string;
@@ -267,6 +293,32 @@ export interface InboxRequestChannel {
267
293
  /** Unacked requests, separated from generic deliveries for exact-match triage. */
268
294
  openRequestsAwaitingMe: InboxOpenRequestRef[];
269
295
  }
296
+ /** Workspace-scoped human history. References confer no access; reads never acknowledge agent work. */
297
+ export interface HumanInboxFeed {
298
+ asOf: string;
299
+ sources: Array<{
300
+ partyId: string;
301
+ partyKind: InboxPartyKind;
302
+ }>;
303
+ items: Array<InboxDeliveryRef & {
304
+ unseen: boolean;
305
+ }>;
306
+ hasMore: boolean;
307
+ /** Opaque pagination token, distinct from both seen and handled marks. */
308
+ nextCursor: string | null;
309
+ /** Human badges: unseen updates plus messages with no exact receipt yet. */
310
+ unread: {
311
+ total: number;
312
+ /** The part of `total` that `seenTo` can clear: unseen non-message updates. */
313
+ updates: number;
314
+ bySource: Array<{
315
+ partyId: string;
316
+ count: number;
317
+ }>;
318
+ };
319
+ /** Explicitly clears update badges through this point, including older rows. Never marks tasks handled. */
320
+ seenTo: string | null;
321
+ }
270
322
  /**
271
323
  * A task whose plan is waiting on the reader's acknowledgement.
272
324
  *
package/dist/index.d.ts CHANGED
@@ -2,7 +2,8 @@
2
2
  * Wire contracts for the Ziggs API.
3
3
  *
4
4
  * The server is authoritative: every shape here is what it actually sends or
5
- * accepts. Nothing in this package reaches the network or reads an
5
+ * accepts, except explicitly marked canonical cutover contracts established
6
+ * before their coordinated runtime installation. Nothing here reaches the network or reads an
6
7
  * environment — it is types plus the closed vocabularies they are built from,
7
8
  * so any runtime can import it.
8
9
  */
@@ -20,5 +21,7 @@ export * from './generated/connections';
20
21
  export * from './generated/agreements';
21
22
  export * from './generated/artifacts';
22
23
  export * from './identifiers';
23
- export * from './generated/chat-send';
24
24
  export * from './execution';
25
+ export * from './messaging';
26
+ export * from './actions';
27
+ export { parseMessageCommand } from './message-command';
package/dist/index.js CHANGED
@@ -14,11 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
14
  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
15
  };
16
16
  Object.defineProperty(exports, "__esModule", { value: true });
17
+ exports.parseMessageCommand = void 0;
17
18
  /**
18
19
  * Wire contracts for the Ziggs API.
19
20
  *
20
21
  * The server is authoritative: every shape here is what it actually sends or
21
- * accepts. Nothing in this package reaches the network or reads an
22
+ * accepts, except explicitly marked canonical cutover contracts established
23
+ * before their coordinated runtime installation. Nothing here reaches the network or reads an
22
24
  * environment — it is types plus the closed vocabularies they are built from,
23
25
  * so any runtime can import it.
24
26
  */
@@ -37,5 +39,8 @@ __exportStar(require("./generated/connections"), exports);
37
39
  __exportStar(require("./generated/agreements"), exports);
38
40
  __exportStar(require("./generated/artifacts"), exports);
39
41
  __exportStar(require("./identifiers"), exports);
40
- __exportStar(require("./generated/chat-send"), exports);
41
42
  __exportStar(require("./execution"), exports);
43
+ __exportStar(require("./messaging"), exports);
44
+ __exportStar(require("./actions"), exports);
45
+ var message_command_1 = require("./message-command");
46
+ Object.defineProperty(exports, "parseMessageCommand", { enumerable: true, get: function () { return message_command_1.parseMessageCommand; } });
@@ -0,0 +1,7 @@
1
+ import type { MessageCommand, ExactArtifactRef, ActionSlotRef } from './index';
2
+ export declare function exactArtifact(value: unknown): ExactArtifactRef;
3
+ export declare function messageAction(value: unknown): Extract<ActionSlotRef, {
4
+ kind: 'message';
5
+ }>;
6
+ /** Strict at every nesting level: identity/authority cannot enter via page JSON. */
7
+ export declare function parseMessageCommand(value: unknown): MessageCommand;
@@ -0,0 +1,219 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.exactArtifact = exactArtifact;
4
+ exports.messageAction = messageAction;
5
+ exports.parseMessageCommand = parseMessageCommand;
6
+ const fail = (field) => {
7
+ throw new Error(`Invalid ${field}`);
8
+ };
9
+ function object(value, keys, field) {
10
+ if (!value || typeof value !== 'object' || Array.isArray(value))
11
+ return fail(field);
12
+ const row = value;
13
+ if (Object.keys(row).some((key) => !keys.includes(key)))
14
+ return fail(`${field}: unknown field`);
15
+ return row;
16
+ }
17
+ function id(value, field, max = 200) {
18
+ if (typeof value !== 'string' || !value.trim() || value.length > max)
19
+ return fail(field);
20
+ return value;
21
+ }
22
+ function revision(value, field) {
23
+ if (!Number.isSafeInteger(value) || Number(value) < 1)
24
+ return fail(field);
25
+ return Number(value);
26
+ }
27
+ function list(value, parse, field, max = 100) {
28
+ if (!Array.isArray(value) || value.length > max)
29
+ return fail(field);
30
+ return value.map(parse);
31
+ }
32
+ function ids(value, field) {
33
+ const values = list(value, (item) => id(item, field), field);
34
+ if (new Set(values).size !== values.length)
35
+ return fail(`${field}: duplicate`);
36
+ return values;
37
+ }
38
+ function exactArtifact(value) {
39
+ const row = object(value, ['kind', 'id', 'sha256'], 'artifact reference');
40
+ if (row.kind !== 'artifact' ||
41
+ typeof row.sha256 !== 'string' ||
42
+ !/^[a-f0-9]{64}$/.test(row.sha256))
43
+ return fail('artifact digest');
44
+ return {
45
+ kind: 'artifact',
46
+ id: id(row.id, 'artifact id'),
47
+ sha256: row.sha256,
48
+ };
49
+ }
50
+ function messageAction(value) {
51
+ const row = object(value, ['kind', 'id', 'slot', 'requestId'], 'answer action');
52
+ if (row.kind !== 'message' || row.slot !== 'answer')
53
+ return fail('answer action');
54
+ return {
55
+ kind: 'message',
56
+ id: id(row.id, 'message id'),
57
+ slot: 'answer',
58
+ requestId: id(row.requestId, 'request id'),
59
+ };
60
+ }
61
+ function source(value) {
62
+ const row = object(value, [
63
+ 'kind',
64
+ 'id',
65
+ 'sha256',
66
+ 'taskId',
67
+ 'revision',
68
+ 'planRevision',
69
+ 'stepId',
70
+ 'url',
71
+ ], 'source');
72
+ switch (row.kind) {
73
+ case 'artifact':
74
+ return exactArtifact(row);
75
+ case 'message':
76
+ object(row, ['kind', 'id'], 'source');
77
+ return { kind: 'message', id: id(row.id, 'source id') };
78
+ case 'task_result':
79
+ object(row, ['kind', 'taskId', 'revision'], 'source');
80
+ return {
81
+ kind: 'task_result',
82
+ taskId: id(row.taskId, 'task id'),
83
+ revision: revision(row.revision, 'result revision'),
84
+ };
85
+ case 'task_plan_step':
86
+ object(row, ['kind', 'taskId', 'planRevision', 'stepId'], 'source');
87
+ return {
88
+ kind: 'task_plan_step',
89
+ taskId: id(row.taskId, 'task id'),
90
+ planRevision: revision(row.planRevision, 'plan revision'),
91
+ stepId: id(row.stepId, 'step id'),
92
+ };
93
+ case 'url': {
94
+ object(row, ['kind', 'url', 'sha256'], 'source');
95
+ const url = id(row.url, 'source URL', 2000);
96
+ if (!/^https?:\/\//.test(url) ||
97
+ typeof row.sha256 !== 'string' ||
98
+ !/^[a-f0-9]{64}$/.test(row.sha256))
99
+ return fail('captured URL source');
100
+ return { kind: 'url', url, sha256: row.sha256 };
101
+ }
102
+ default:
103
+ return fail('source kind');
104
+ }
105
+ }
106
+ /** Strict at every nesting level: identity/authority cannot enter via page JSON. */
107
+ function parseMessageCommand(value) {
108
+ const row = object(value, [
109
+ 'operationId',
110
+ 'content',
111
+ 'audience',
112
+ 'deliveries',
113
+ 'effect',
114
+ 'sources',
115
+ 'mandate',
116
+ 'relationships',
117
+ ], 'message command');
118
+ const content = object(row.content, ['text'], 'content');
119
+ const audience = object(row.audience, ['kind', 'principalIds'], 'audience');
120
+ const deliveries = object(row.deliveries, ['kind', 'principalIds'], 'deliveries');
121
+ const effect = object(row.effect, ['kind', 'requests', 'action', 'artifacts'], 'effect');
122
+ if (audience.kind !== 'explicit')
123
+ return fail('audience kind');
124
+ const audienceValue = {
125
+ kind: 'explicit',
126
+ principalIds: ids(audience.principalIds, 'readers'),
127
+ };
128
+ if (deliveries.kind !== 'explicit')
129
+ return fail('delivery kind');
130
+ const deliveryValue = {
131
+ kind: 'explicit',
132
+ principalIds: ids(deliveries.principalIds, 'recipients'),
133
+ };
134
+ let effectValue;
135
+ switch (effect.kind) {
136
+ case 'none':
137
+ object(effect, ['kind'], 'effect');
138
+ effectValue = { kind: 'none' };
139
+ break;
140
+ case 'request-answers': {
141
+ object(effect, ['kind', 'requests'], 'effect');
142
+ const requests = list(effect.requests, (item) => {
143
+ const r = object(item, ['requestId', 'responsiblePrincipalId'], 'answer request');
144
+ return {
145
+ requestId: id(r.requestId, 'request id'),
146
+ responsiblePrincipalId: id(r.responsiblePrincipalId, 'responsible principal'),
147
+ };
148
+ }, 'answer requests');
149
+ if (!requests.length ||
150
+ new Set(requests.map((r) => r.requestId)).size !== requests.length)
151
+ return fail('answer request identities');
152
+ effectValue = { kind: 'request-answers', requests };
153
+ break;
154
+ }
155
+ case 'answer':
156
+ object(effect, ['kind', 'action', 'artifacts'], 'effect');
157
+ effectValue = {
158
+ kind: 'answer',
159
+ action: messageAction(effect.action),
160
+ artifacts: list(effect.artifacts, exactArtifact, 'answer artifacts'),
161
+ };
162
+ break;
163
+ case 'provide-input': {
164
+ object(effect, ['kind', 'action'], 'effect');
165
+ const action = object(effect.action, ['kind', 'id', 'slot', 'requestId'], 'input action');
166
+ if (action.kind === 'message')
167
+ effectValue = { kind: 'provide-input', action: messageAction(action) };
168
+ else if (action.kind === 'task' && action.slot === 'process') {
169
+ object(action, ['kind', 'id', 'slot'], 'input action');
170
+ effectValue = {
171
+ kind: 'provide-input',
172
+ action: {
173
+ kind: 'task',
174
+ id: id(action.id, 'task id'),
175
+ slot: 'process',
176
+ },
177
+ };
178
+ }
179
+ else
180
+ return fail('input action');
181
+ break;
182
+ }
183
+ default:
184
+ return fail('effect kind');
185
+ }
186
+ const command = {
187
+ operationId: id(row.operationId, 'operation id', 128),
188
+ content: { text: id(content.text, 'message text', 32000) },
189
+ audience: audienceValue,
190
+ deliveries: deliveryValue,
191
+ effect: effectValue,
192
+ };
193
+ if (row.sources !== undefined)
194
+ command.sources = list(row.sources, source, 'sources', 50);
195
+ if (row.mandate !== undefined) {
196
+ const mandate = object(row.mandate, ['agreementId', 'taskId'], 'mandate');
197
+ command.mandate = {
198
+ agreementId: id(mandate.agreementId, 'agreement id'),
199
+ ...(mandate.taskId !== undefined
200
+ ? { taskId: id(mandate.taskId, 'task id') }
201
+ : {}),
202
+ };
203
+ }
204
+ if (row.relationships !== undefined) {
205
+ const rel = object(row.relationships, ['replyToMessageId', 'taskIds', 'artifacts'], 'relationships');
206
+ command.relationships = {
207
+ ...(rel.replyToMessageId !== undefined
208
+ ? { replyToMessageId: id(rel.replyToMessageId, 'reply target') }
209
+ : {}),
210
+ ...(rel.taskIds !== undefined
211
+ ? { taskIds: ids(rel.taskIds, 'task links') }
212
+ : {}),
213
+ ...(rel.artifacts !== undefined
214
+ ? { artifacts: list(rel.artifacts, exactArtifact, 'artifact links') }
215
+ : {}),
216
+ };
217
+ }
218
+ return command;
219
+ }
@@ -0,0 +1,145 @@
1
+ /** Messaging primitives shared by all interfaces. Endpoint references convey no permission. */
2
+ export type MessageIntent = 'request' | 'notify' | 'contribute';
3
+ export interface MessageEndpoint {
4
+ ref: string;
5
+ name: string;
6
+ kind: string;
7
+ isSelf: boolean;
8
+ /** Who this is, the same in every message: an agent's own id, a person's
9
+ * or workspace's persona id (never a user id, which carries an email).
10
+ * Draws their face and, for an agent, their presence; it addresses nothing. */
11
+ faceId: string;
12
+ image: string | null;
13
+ }
14
+ /** Discovery only. Sending rechecks recipient, authority, consent and allowance. */
15
+ export interface MessagingControls {
16
+ canSend: boolean;
17
+ recipients: MessageEndpoint[];
18
+ }
19
+ /** Each artifact id names one immutable version. The digest binds the reference
20
+ * to exact UTF-8 text or file bytes; a successor uses a new id. A mutable managed
21
+ * source must first be captured as an immutable artifact. No implicit "latest". */
22
+ export interface ExactArtifactRef {
23
+ kind: 'artifact';
24
+ id: string;
25
+ sha256: string;
26
+ }
27
+ export type MessageSourceRef = ExactArtifactRef | {
28
+ kind: 'message';
29
+ id: string;
30
+ }
31
+ /** One-based immutable native Task.history entry containing the result. */
32
+ | {
33
+ kind: 'task_result';
34
+ taskId: string;
35
+ revision: number;
36
+ } | {
37
+ kind: 'task_plan_step';
38
+ taskId: string;
39
+ /** One-based native Task.history entry containing this step change. */
40
+ planRevision: number;
41
+ stepId: string;
42
+ } | {
43
+ kind: 'url';
44
+ url: string;
45
+ sha256: string;
46
+ };
47
+ /** Who may read the message. Every message names its own readers; nothing is saved for reuse. */
48
+ export type MessageReadAudience = {
49
+ kind: 'explicit';
50
+ principalIds: string[];
51
+ };
52
+ /** Whose inbox it lands in. Each one must also be a reader. */
53
+ export type MessageDeliveries = {
54
+ kind: 'explicit';
55
+ principalIds: string[];
56
+ };
57
+ export type MessageActionEffect = {
58
+ kind: 'none';
59
+ } | {
60
+ kind: 'request-answers';
61
+ requests: Array<{
62
+ requestId: string;
63
+ responsiblePrincipalId: string;
64
+ }>;
65
+ } | {
66
+ kind: 'provide-input';
67
+ action: import('./actions').ActionSlotRef;
68
+ } | {
69
+ kind: 'answer';
70
+ action: Extract<import('./actions').ActionSlotRef, {
71
+ kind: 'message';
72
+ }>;
73
+ artifacts: ExactArtifactRef[];
74
+ };
75
+ export interface MessageCommand {
76
+ /** Authenticated accountable principal scopes this identity. Changed input conflicts. */
77
+ operationId: string;
78
+ content: {
79
+ text: string;
80
+ };
81
+ /** Server validates sharing; delivery does not itself grant these rights. */
82
+ audience: MessageReadAudience;
83
+ /** Resolve once and persist the snapshot atomically with the message. */
84
+ deliveries: MessageDeliveries;
85
+ effect: MessageActionEffect;
86
+ /** Private provenance, never included in the message presentation. */
87
+ sources?: MessageSourceRef[];
88
+ /** Required when the selected work/spending relies on an agreement. No fallback. */
89
+ mandate?: {
90
+ agreementId: string;
91
+ taskId?: string;
92
+ };
93
+ /** Links do not route, grant, assign, charge, or resolve an answer request. */
94
+ relationships?: {
95
+ replyToMessageId?: string;
96
+ taskIds?: string[];
97
+ artifacts?: ExactArtifactRef[];
98
+ };
99
+ }
100
+ /** One viewer-safe presentation for every message; no work/direct/shared variant. */
101
+ export interface MessageRecord {
102
+ messageId: string;
103
+ timestamp: string;
104
+ content: MessageCommand['content'];
105
+ sender: MessageEndpoint;
106
+ readers: MessageEndpoint[];
107
+ recipients: MessageEndpoint[];
108
+ /** Owned slots; their outcomes are separate from this immutable record. */
109
+ requestedAnswers: Array<{
110
+ action: Extract<import('./actions').ActionSlotRef, {
111
+ kind: 'message';
112
+ }>;
113
+ responsible: MessageEndpoint;
114
+ }>;
115
+ /** Only references the viewer may discover; unreadable links are omitted. */
116
+ relationships: NonNullable<MessageCommand['relationships']>;
117
+ /** Null unless the viewer may read this mandate; never infer authority from it. */
118
+ mandate: MessageCommand['mandate'] | null;
119
+ /** What the message does: FYI, asks, answers or gives input. Action ids stay with their owner. */
120
+ effect: MessageCommand['effect']['kind'];
121
+ /** The outside channel it arrived through, without its provider reference. */
122
+ importedFrom: {
123
+ channel: 'slack' | 'email' | 'github';
124
+ } | null;
125
+ }
126
+ export interface MessageCommandResult {
127
+ outcome: 'created' | 'existing';
128
+ message: MessageRecord;
129
+ }
130
+ /** Optional contact routing configuration owns no history, grants or work. */
131
+ export interface ContactAlias {
132
+ aliasId: string;
133
+ ownerPrincipalId: string;
134
+ target: {
135
+ kind: 'principal';
136
+ principalId: string;
137
+ } | {
138
+ kind: 'selection';
139
+ selectionId: string;
140
+ };
141
+ open: boolean;
142
+ }
143
+ /** Authenticated owner, not a field accepted from message content or a page. */
144
+ export declare function messageOperationKey(authenticatedOwnerId: string, operationId: string): string;
145
+ export declare function exactArtifactKey(ref: ExactArtifactRef): string;
@@ -0,0 +1,17 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.messageOperationKey = messageOperationKey;
4
+ exports.exactArtifactKey = exactArtifactKey;
5
+ /** Authenticated owner, not a field accepted from message content or a page. */
6
+ function messageOperationKey(authenticatedOwnerId, operationId) {
7
+ if (!authenticatedOwnerId.trim() || !operationId.trim())
8
+ throw new Error('Operation owner and identity are required');
9
+ return JSON.stringify([authenticatedOwnerId, operationId]);
10
+ }
11
+ function exactArtifactKey(ref) {
12
+ if (ref.kind !== 'artifact' ||
13
+ !ref.id.trim() ||
14
+ !/^[a-f0-9]{64}$/.test(ref.sha256))
15
+ throw new Error('An exact artifact id and lowercase SHA-256 digest are required');
16
+ return JSON.stringify([ref.kind, ref.id, ref.sha256]);
17
+ }