@ziggs-ai/contracts 0.44.0 → 0.46.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/actions.d.ts CHANGED
@@ -2,13 +2,13 @@
2
2
  export type ActionRef = {
3
3
  kind: 'task' | 'agreement' | 'permission-request' | 'request';
4
4
  id: string;
5
- } | {
5
+ }
6
+ /** A request message an agent was sent: the one thing a direct-conversation
7
+ * execution binds to. Nothing is "answered"; a reply is a message linking back. */
8
+ | {
6
9
  kind: 'message';
7
10
  id: string;
8
- slot: 'answer';
9
- requestId: string;
10
11
  };
11
- /** Message slots must remain distinct even when the same principal owns two. */
12
12
  export declare function actionKey(action: ActionRef): string;
13
13
  /** Canonical action identity for the Step 2/3 cutover. Current owner-only
14
14
  * ActionRef consumers are inventoried; no runtime format fallback is provided.
@@ -23,11 +23,6 @@ export type ActionSlotRef = {
23
23
  slot: 'plan-approval';
24
24
  revision: number;
25
25
  principalId: string;
26
- } | {
27
- kind: 'message';
28
- id: string;
29
- slot: 'answer';
30
- requestId: string;
31
26
  } | {
32
27
  kind: 'permission-request' | 'agreement';
33
28
  id: string;
package/dist/actions.js CHANGED
@@ -2,11 +2,8 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.actionKey = actionKey;
4
4
  exports.actionSlotKey = actionSlotKey;
5
- /** Message slots must remain distinct even when the same principal owns two. */
6
5
  function actionKey(action) {
7
- return action.kind === 'message'
8
- ? actionSlotKey(action)
9
- : JSON.stringify([action.kind, action.id]);
6
+ return JSON.stringify([action.kind, action.id]);
10
7
  }
11
8
  /** Stable across retries and executor replacement; intentionally excludes owner
12
9
  * revision for processing, but identifies a specific proposed plan/decision. */
@@ -31,15 +28,6 @@ function actionSlotKey(action) {
31
28
  action.revision,
32
29
  action.principalId,
33
30
  ]);
34
- case 'answer':
35
- if (action.kind !== 'message' || !action.requestId?.trim())
36
- throw new Error('Exact answer request is required');
37
- return JSON.stringify([
38
- action.kind,
39
- action.id,
40
- action.slot,
41
- action.requestId,
42
- ]);
43
31
  case 'decision':
44
32
  if (!['permission-request', 'agreement'].includes(action.kind) ||
45
33
  !action.decisionId?.trim() ||
@@ -3,7 +3,7 @@
3
3
  * Family: grants. Regenerate: backend 'pnpm docs:generate' then this script.
4
4
  */
5
5
  export type GrantScopeView = {
6
- kind: "message" | "address" | "agreement" | "org" | "artifact" | "task" | "person" | "connection" | "wallet" | "consent" | "inbox";
6
+ kind: "message" | "address" | "agreement" | "org" | "artifact" | "task" | "person" | "contact" | "connection" | "wallet" | "consent" | "inbox";
7
7
  id: string;
8
8
  label?: string;
9
9
  };
@@ -12,7 +12,7 @@ export type GrantCaveatView = {
12
12
  value: unknown;
13
13
  };
14
14
  export type GrantBasis = {
15
- kind: "creation" | "publication" | "membership" | "acceptance" | "agreement" | "vouch" | "owner";
15
+ kind: "creation" | "publication" | "membership" | "acceptance" | "agreement" | "vouch" | "owner" | "contact";
16
16
  id: string | null;
17
17
  };
18
18
  export type GrantView = {
package/dist/inbox.d.ts CHANGED
@@ -76,7 +76,8 @@ export interface AccessAsk {
76
76
  * `list` (ZIG-2170) is asked of a person scope: which rooms they are in,
77
77
  * never what is in them.
78
78
  */
79
- permission?: 'list' | 'read' | 'reply';
79
+ /** `send` (ZIG-2321): one-way permission to message the scope's destination; no read. */
80
+ permission?: 'list' | 'read' | 'reply' | 'send';
80
81
  /** The one thing. `name` is absent when nothing readable resolves. */
81
82
  scope: {
82
83
  kind: string;
@@ -227,21 +228,11 @@ export type AttentionEntry = {
227
228
  at: string;
228
229
  source: 'notice';
229
230
  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
- };
240
231
  };
241
232
  /** How many notice rows one attention window can carry. */
242
233
  export declare const INBOX_ATTENTION_NOTICE_CAP = 50;
243
234
  /**
244
- * `GET /inbox/attention` — what needs an answer, then what needs eyes.
235
+ * `GET /inbox/attention` — what needs a decision, then what needs eyes.
245
236
  *
246
237
  * A window onto the one party-owned log, not a log of its own. Three rules
247
238
  * hold it to that:
@@ -256,14 +247,12 @@ export declare const INBOX_ATTENTION_NOTICE_CAP = 50;
256
247
  */
257
248
  export interface AttentionFeed {
258
249
  asOf: string;
259
- /** Decisions first — somebody is blocked on those — then questions to answer, then notices, newest first. */
250
+ /** Decisions first — somebody is blocked on those — then notices, newest first. */
260
251
  items: AttentionEntry[];
261
252
  /** Decisions the server capped. Nothing local can expand into them. */
262
253
  truncated: number;
263
254
  /** Older unseen notice rows exist past the cap; they stay unseen. */
264
255
  hasMore: boolean;
265
- /** Older readable pending questions. Pass verbatim as answerBefore to GET /inbox/attention. */
266
- answerNextCursor: string | null;
267
256
  /**
268
257
  * Opaque token for `POST /inbox/seen`, covering the notice rows above and
269
258
  * nothing else. Null when the block carried no notices. Never constructed
@@ -1,7 +1,4 @@
1
- import type { MessageCommand, ExactArtifactRef, ActionSlotRef } from './index';
1
+ import type { MessageCommand, ExactArtifactRef } from './index';
2
2
  export declare function exactArtifact(value: unknown): ExactArtifactRef;
3
- export declare function messageAction(value: unknown): Extract<ActionSlotRef, {
4
- kind: 'message';
5
- }>;
6
3
  /** Strict at every nesting level: identity/authority cannot enter via page JSON. */
7
4
  export declare function parseMessageCommand(value: unknown): MessageCommand;
@@ -1,7 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.exactArtifact = exactArtifact;
4
- exports.messageAction = messageAction;
5
4
  exports.parseMessageCommand = parseMessageCommand;
6
5
  const fail = (field) => {
7
6
  throw new Error(`Invalid ${field}`);
@@ -47,17 +46,6 @@ function exactArtifact(value) {
47
46
  sha256: row.sha256,
48
47
  };
49
48
  }
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
49
  function source(value) {
62
50
  const row = object(value, [
63
51
  'kind',
@@ -110,7 +98,7 @@ function parseMessageCommand(value) {
110
98
  'content',
111
99
  'audience',
112
100
  'deliveries',
113
- 'effect',
101
+ 'intent',
114
102
  'sources',
115
103
  'mandate',
116
104
  'relationships',
@@ -118,7 +106,6 @@ function parseMessageCommand(value) {
118
106
  const content = object(row.content, ['text'], 'content');
119
107
  const audience = object(row.audience, ['kind', 'principalIds'], 'audience');
120
108
  const deliveries = object(row.deliveries, ['kind', 'principalIds'], 'deliveries');
121
- const effect = object(row.effect, ['kind', 'requests', 'action', 'artifacts'], 'effect');
122
109
  if (audience.kind !== 'explicit')
123
110
  return fail('audience kind');
124
111
  const audienceValue = {
@@ -131,64 +118,14 @@ function parseMessageCommand(value) {
131
118
  kind: 'explicit',
132
119
  principalIds: ids(deliveries.principalIds, 'recipients'),
133
120
  };
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
- // Published 0.43 clients require this field. Normalize the empty wire
158
- // value away; actual files use relationships.artifacts on every message.
159
- if (effect.artifacts !== undefined)
160
- list(effect.artifacts, exactArtifact, 'answer artifacts', 0);
161
- effectValue = { kind: 'answer', action: messageAction(effect.action) };
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
- }
121
+ if (row.intent !== 'fyi' && row.intent !== 'request')
122
+ return fail('intent');
186
123
  const command = {
187
124
  operationId: id(row.operationId, 'operation id', 128),
188
125
  content: { text: id(content.text, 'message text', 32000) },
189
126
  audience: audienceValue,
190
127
  deliveries: deliveryValue,
191
- effect: effectValue,
128
+ intent: row.intent,
192
129
  };
193
130
  if (row.sources !== undefined)
194
131
  command.sources = list(row.sources, source, 'sources', 50);
@@ -1,5 +1,8 @@
1
1
  /** Messaging primitives shared by all interfaces. Endpoint references convey no permission. */
2
- export type MessageIntent = 'request' | 'notify' | 'contribute';
2
+ /** The one flag a message carries. A request wakes the agents it is sent to
3
+ * (or only the ones named in the text); an FYI is delivered and filed, never
4
+ * woken on. Nothing records whether a request was answered. */
5
+ export type MessageIntent = 'fyi' | 'request';
3
6
  export interface MessageEndpoint {
4
7
  ref: string;
5
8
  name: string;
@@ -54,27 +57,6 @@ export type MessageDeliveries = {
54
57
  kind: 'explicit';
55
58
  principalIds: string[];
56
59
  };
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
- /** Files on an answer go in relationships.artifacts, like any message. */
70
- | {
71
- kind: 'answer';
72
- action: Extract<import('./actions').ActionSlotRef, {
73
- kind: 'message';
74
- }>;
75
- /** @deprecated Accepted empty for published 0.43 clients; files belong in relationships. */
76
- artifacts?: [];
77
- };
78
60
  export interface MessageCommand {
79
61
  /** Authenticated accountable principal scopes this identity. Changed input conflicts. */
80
62
  operationId: string;
@@ -85,7 +67,7 @@ export interface MessageCommand {
85
67
  audience: MessageReadAudience;
86
68
  /** Resolve once and persist the snapshot atomically with the message. */
87
69
  deliveries: MessageDeliveries;
88
- effect: MessageActionEffect;
70
+ intent: MessageIntent;
89
71
  /** Private provenance: only the sender sees it back, as `sentFrom`. */
90
72
  sources?: MessageSourceRef[];
91
73
  /** Required when the selected work/spending relies on an agreement. No fallback. */
@@ -93,7 +75,7 @@ export interface MessageCommand {
93
75
  agreementId: string;
94
76
  taskId?: string;
95
77
  };
96
- /** Links do not route, grant, assign, charge, or resolve an answer request. */
78
+ /** Links do not route, grant, assign or charge. */
97
79
  relationships?: {
98
80
  replyToMessageId?: string;
99
81
  taskIds?: string[];
@@ -108,19 +90,11 @@ export interface MessageRecord {
108
90
  sender: MessageEndpoint;
109
91
  readers: MessageEndpoint[];
110
92
  recipients: MessageEndpoint[];
111
- /** Owned slots; their outcomes are separate from this immutable record. */
112
- requestedAnswers: Array<{
113
- action: Extract<import('./actions').ActionSlotRef, {
114
- kind: 'message';
115
- }>;
116
- responsible: MessageEndpoint;
117
- }>;
118
93
  /** Only references the viewer may discover; unreadable links are omitted. */
119
94
  relationships: NonNullable<MessageCommand['relationships']>;
120
95
  /** Null unless the viewer may read this mandate; never infer authority from it. */
121
96
  mandate: MessageCommand['mandate'] | null;
122
- /** What the message does: FYI, asks, answers or gives input. Action ids stay with their owner. */
123
- effect: MessageCommand['effect']['kind'];
97
+ intent: MessageIntent;
124
98
  /** The outside channel it arrived through, without its provider reference. */
125
99
  importedFrom: {
126
100
  channel: 'slack' | 'email' | 'github';
@@ -135,12 +135,12 @@ export declare const AGREEMENT_TERMINAL_STATES: readonly AgreementStatusValue[];
135
135
  * Context-rail scopes, then the other rails a grant can name.
136
136
  * Order is the order the grants read and the OpenAPI enum publish.
137
137
  */
138
- export declare const CONTEXT_GRANT_SCOPE_KINDS: readonly ["message", "address", "agreement", "org", "artifact", "task", "person"];
139
- export declare const GRANT_SCOPE_KINDS: readonly ["message", "address", "agreement", "org", "artifact", "task", "person", "connection", "wallet", "consent", "inbox"];
138
+ export declare const CONTEXT_GRANT_SCOPE_KINDS: readonly ["message", "address", "agreement", "org", "artifact", "task", "person", "contact"];
139
+ export declare const GRANT_SCOPE_KINDS: readonly ["message", "address", "agreement", "org", "artifact", "task", "person", "contact", "connection", "wallet", "consent", "inbox"];
140
140
  export type GrantScopeKind = (typeof GRANT_SCOPE_KINDS)[number];
141
141
  export type ContextGrantScopeKind = (typeof CONTEXT_GRANT_SCOPE_KINDS)[number];
142
142
  /** What an access request may name. Always one resource. */
143
- export declare const ACCESS_REQUEST_SCOPE_KINDS: readonly ["message", "artifact", "agreement", "task"];
143
+ export declare const ACCESS_REQUEST_SCOPE_KINDS: readonly ["message", "artifact", "agreement", "task", "contact"];
144
144
  export type AccessRequestScopeKind = (typeof ACCESS_REQUEST_SCOPE_KINDS)[number];
145
145
  /**
146
146
  * Who an artifact access request may ask a grant FOR. Each reader is named
@@ -160,6 +160,10 @@ exports.CONTEXT_GRANT_SCOPE_KINDS = [
160
160
  'task',
161
161
  // Historical person-wide room discovery. New grants cannot use this scope.
162
162
  'person',
163
+ // A one-way send grant: the holder may send messages to this destination
164
+ // principal (scope id). Held at write only, never delegated, and minted only
165
+ // by an approved access request.
166
+ 'contact',
163
167
  ];
164
168
  exports.GRANT_SCOPE_KINDS = [
165
169
  ...exports.CONTEXT_GRANT_SCOPE_KINDS,
@@ -174,6 +178,9 @@ exports.ACCESS_REQUEST_SCOPE_KINDS = [
174
178
  'artifact',
175
179
  'agreement',
176
180
  'task',
181
+ // Permission to send messages to one destination (a person, an agent, or a
182
+ // workspace inbox). Its approver is the destination's owner.
183
+ 'contact',
177
184
  ];
178
185
  /**
179
186
  * Who an artifact access request may ask a grant FOR. Each reader is named
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ziggs-ai/contracts",
3
- "version": "0.44.0",
3
+ "version": "0.46.0",
4
4
  "description": "Wire contracts for the Ziggs API — response shapes, error body, and socket events, shared by every client.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",