@kana-ai/edgar-contracts 0.1.2 → 0.1.3

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.
@@ -22,6 +22,10 @@ export declare const cardBlock: z.ZodObject<{
22
22
  channel: z.ZodString;
23
23
  thread: z.ZodString;
24
24
  }, z.core.$strict>>;
25
+ trust: z.ZodExactOptional<z.ZodEnum<{
26
+ outside: "outside";
27
+ team: "team";
28
+ }>>;
25
29
  }, z.core.$strict>;
26
30
  /** The card a tool files; its output type is the contract's `CardSpec`. */
27
31
  export declare const cardSpec: z.ZodObject<{
@@ -51,5 +55,9 @@ export declare const cardSpec: z.ZodObject<{
51
55
  channel: z.ZodString;
52
56
  thread: z.ZodString;
53
57
  }, z.core.$strict>>;
58
+ trust: z.ZodExactOptional<z.ZodEnum<{
59
+ outside: "outside";
60
+ team: "team";
61
+ }>>;
54
62
  }, z.core.$strict>;
55
63
  }, z.core.$strict>;
@@ -22,6 +22,7 @@ export const cardBlock = z.strictObject({
22
22
  thread: z.string().min(1),
23
23
  })
24
24
  .exactOptional(),
25
+ trust: z.enum(["team", "outside"]).exactOptional(),
25
26
  });
26
27
  /** The card a tool files; its output type is the contract's `CardSpec`. */
27
28
  export const cardSpec = z.strictObject({
@@ -27,6 +27,7 @@ export type TrackerMethod =
27
27
  | "list_cards"
28
28
  | "card"
29
29
  | "comments"
30
+ | "mentions"
30
31
  | "attachments"
31
32
  | "comment"
32
33
  | "move"
@@ -63,6 +64,10 @@ export interface Manifest {
63
64
  hooks: Hook[];
64
65
  service?: Service;
65
66
  git_credential?: GitCredential;
67
+ publish_commits?: PublishCommits;
68
+ identity?: Identity;
69
+ read_link?: ReadLink;
70
+ chat_files?: ChatFiles;
66
71
  executables?: Executables;
67
72
  }
68
73
  /**
@@ -87,6 +92,10 @@ export interface Tool {
87
92
  input_schema: string;
88
93
  output_schema: string;
89
94
  side_effect: boolean;
95
+ /**
96
+ * Its input is text that people read, such as a comment, a pull request or a message; EDGAR hides email addresses in it.
97
+ */
98
+ publishes?: boolean;
90
99
  compensate?: Name;
91
100
  lookup?: Name;
92
101
  undo?: "none";
@@ -108,6 +117,10 @@ export interface Webhook {
108
117
  signature: "hmac-sha256" | "ed25519" | "none";
109
118
  secret: SecretName | null;
110
119
  delivery_id_header: string | null;
120
+ /**
121
+ * The header that carries the signature of a delivery, as `<hex>` or `sha256=<hex>`; a tracker's webhook needs it.
122
+ */
123
+ signature_header?: string | null;
111
124
  }
112
125
  /**
113
126
  * The tracker port; the engine calls `tracker.<method>` through `tool.call`.
@@ -189,7 +202,7 @@ export interface Service {
189
202
  capabilities: Capability[];
190
203
  }
191
204
  /**
192
- * What runs `tool.call` of `git_credential`, which answers `{ token, expires_at_ms }` for the engine's git to send to a host of `[sandbox] git_tokens` that names the extension; the engine asks again before `expires_at_ms`, and keeps the token in memory only.
205
+ * What runs `tool.call` of `git_credential` with `{ host, repository, access }`, the one repository and the read or write access of a git step, which answers `{ token, expires_at_ms }` of a token that covers no more, for the engine's git to send to a host of `[sandbox] git_tokens` that names the extension; the engine asks again before `expires_at_ms`, and keeps the token in memory only.
193
206
  *
194
207
  * This interface was referenced by `Manifest`'s JSON-Schema
195
208
  * via the `definition` "GitCredential".
@@ -198,6 +211,57 @@ export interface GitCredential {
198
211
  secrets: SecretName[];
199
212
  capabilities: Capability[];
200
213
  }
214
+ /**
215
+ * What runs `tool.call` of `publish_commits` for a push on a host of `[sandbox] signed_commits` that names the extension. The engine calls it with `{ host, repository, branch, from, base, commits }`: the commits of the push, oldest first, each `{ id, tree, message, changes }` with each file it writes (`{ kind: "write", path, mode, blob, content }`, the bytes in base64) or deletes (`{ kind: "delete", path }`). The extension makes each commit on the one before, `base` first, so the host signs it, then moves `branch` from `from`, or makes it when `from` is `null`, without force. It answers `{ commits }`, the id of each commit it made in the same order; the engine fetches them and refuses any whose tree differs from its planned commit's.
216
+ *
217
+ * This interface was referenced by `Manifest`'s JSON-Schema
218
+ * via the `definition` "PublishCommits".
219
+ */
220
+ export interface PublishCommits {
221
+ secrets: SecretName[];
222
+ capabilities: Capability[];
223
+ }
224
+ /**
225
+ * What runs `tool.call` of `identity`, which says who sends a request by the host of `[api] public_url` for a project whose `[api] identity` names the extension. The engine calls it with `{ headers }`, holding only the listed request headers that the request carries, and takes `{ email, expires_at_ms }`, which it keeps in memory until `expires_at_ms`, or a failure, which refuses the request. `authorization`, `cookie` and `host` are never handed over.
226
+ *
227
+ * This interface was referenced by `Manifest`'s JSON-Schema
228
+ * via the `definition` "Identity".
229
+ */
230
+ export interface Identity {
231
+ /**
232
+ * @minItems 1
233
+ */
234
+ headers: [string, ...string[]];
235
+ secrets: SecretName[];
236
+ capabilities: Capability[];
237
+ }
238
+ /**
239
+ * What runs `tool.call` of `read_link`, which reads a link that a card or its comments hold. When a run starts, the engine calls it with `{ url }` for each `https` link whose host is one of `hosts` (`*.<domain>` names each host under the domain), and takes `{ kind: "read", title, text }`, `{ kind: "not_mine" }` for a link it does not read, or a failure. The engine writes what it reads in the run's inbox, cut to its caps, with secrets and emails hidden, and never follows a link inside that text.
240
+ *
241
+ * This interface was referenced by `Manifest`'s JSON-Schema
242
+ * via the `definition` "ReadLink".
243
+ */
244
+ export interface ReadLink {
245
+ /**
246
+ * @minItems 1
247
+ */
248
+ hosts: [string, ...string[]];
249
+ secrets: SecretName[];
250
+ capabilities: Capability[];
251
+ }
252
+ /**
253
+ * The files a person shares in a chat with the service. When a chat lists a file whose url is `https` on one of `hosts`, each named in full, the engine fetches it into the run's inbox with the value of `secret` as its bearer token, under the same caps as a card's attachments and with secrets masked in a text file. A file on any other host is not fetched, and no other fetch carries the token.
254
+ *
255
+ * This interface was referenced by `Manifest`'s JSON-Schema
256
+ * via the `definition` "ChatFiles".
257
+ */
258
+ export interface ChatFiles {
259
+ /**
260
+ * @minItems 1
261
+ */
262
+ hosts: [string, ...string[]];
263
+ secret: SecretName;
264
+ }
201
265
  /**
202
266
  * The programs the extension runs: `requires` must be on the machine, and `provides` are files the extension ships. `edgar check` refuses a project that lacks one.
203
267
  *
@@ -27,6 +27,7 @@ export type Method =
27
27
  | "tracker.list_cards"
28
28
  | "tracker.card"
29
29
  | "tracker.comments"
30
+ | "tracker.mentions"
30
31
  | "tracker.attachments"
31
32
  | "tracker.comment"
32
33
  | "tracker.move"
@@ -37,6 +38,7 @@ export type Method =
37
38
  | "tracker.person"
38
39
  | "complete"
39
40
  | "runs.read"
41
+ | "pictures.publish"
40
42
  | "service.request";
41
43
  /**
42
44
  * `<run id>:<stage>:<attempt>:<call sequence>`.
@@ -67,6 +69,20 @@ export type MaxMessageBytes = 4194304;
67
69
  * via the `definition` "Contract".
68
70
  */
69
71
  export type Contract = 1;
72
+ /**
73
+ * A card's priority, as a person sets it in the tracker. A queued run of an urgent card starts first, then one of a high card, then the others, each by age.
74
+ *
75
+ * This interface was referenced by `Rpc`'s JSON-Schema
76
+ * via the `definition` "Priority".
77
+ */
78
+ export type Priority = "urgent" | "high";
79
+ /**
80
+ * Whether the person who wrote a card or a comment is on the team, as the tracker knows it, such as a collaborator of a repository or a member of a workspace.
81
+ *
82
+ * This interface was referenced by `Rpc`'s JSON-Schema
83
+ * via the `definition` "Trust".
84
+ */
85
+ export type Trust = "team" | "outside";
70
86
  /**
71
87
  * This interface was referenced by `Rpc`'s JSON-Schema
72
88
  * via the `definition` "Encoding".
@@ -128,6 +144,10 @@ export type ServiceRequest =
128
144
  outcome: Outcome;
129
145
  by: string;
130
146
  }
147
+ | {
148
+ kind: "moves.allowed";
149
+ by: string;
150
+ }
131
151
  | {
132
152
  kind: "moves.approve";
133
153
  operation: string;
@@ -160,6 +180,7 @@ export type ServiceRequest =
160
180
  card?: string;
161
181
  text: string;
162
182
  by: string;
183
+ trust?: Trust2;
163
184
  origin?: Origin;
164
185
  })
165
186
  | {
@@ -168,7 +189,28 @@ export type ServiceRequest =
168
189
  by: string;
169
190
  origin: Origin;
170
191
  card: CardSpec;
192
+ files?: Attachment[];
193
+ }
194
+ | {
195
+ kind: "inbox.receive";
196
+ delivery: string;
197
+ payload: string;
198
+ }
199
+ | {
200
+ kind: "inbox.pending";
201
+ }
202
+ | {
203
+ kind: "inbox.handled";
204
+ delivery: string;
171
205
  };
206
+ /**
207
+ * Set by a service that opens the card for a person: `outside` when that person is outside the team, which makes the card's trust `outside` whoever the tracker says wrote it.
208
+ */
209
+ export type Trust1 = "team" | "outside";
210
+ /**
211
+ * Whether the person who wrote a card or a comment is on the team, as the tracker knows it, such as a collaborator of a repository or a member of a workspace.
212
+ */
213
+ export type Trust2 = "team" | "outside";
172
214
  /**
173
215
  * The output of `hook.<name>`; a deny becomes `permanent_failure(denied_by_hook)`.
174
216
  *
@@ -191,6 +233,14 @@ export type HookDecision =
191
233
  * via the `definition` "ApprovalDecision".
192
234
  */
193
235
  export type ApprovalDecision = "never" | "always";
236
+ /**
237
+ * Whether the person who wrote the card is on the team; a tracker that does not say is read as outside.
238
+ */
239
+ export type Trust3 = "team" | "outside";
240
+ /**
241
+ * Whether `author` is on the team; a tracker that does not say is read as outside.
242
+ */
243
+ export type Trust4 = "team" | "outside";
194
244
 
195
245
  /**
196
246
  * The JSON-RPC 2.0 messages between the engine and `edgar-runtime`; this document only holds definitions.
@@ -462,6 +512,26 @@ export interface Waiting {
462
512
  export interface CompleteResult {
463
513
  applied: boolean;
464
514
  }
515
+ /**
516
+ * `pictures.publish`: the PNG at `path` in the sandbox, at most 2 MB.
517
+ *
518
+ * This interface was referenced by `Rpc`'s JSON-Schema
519
+ * via the `definition` "PicturesPublishParams".
520
+ */
521
+ export interface PicturesPublishParams {
522
+ operation_id: OperationId;
523
+ path: string;
524
+ }
525
+ /**
526
+ * The picture's content id, and the stable address that shows it.
527
+ *
528
+ * This interface was referenced by `Rpc`'s JSON-Schema
529
+ * via the `definition` "PicturesPublishResult".
530
+ */
531
+ export interface PicturesPublishResult {
532
+ id: string;
533
+ url: string;
534
+ }
465
535
  /**
466
536
  * This interface was referenced by `Rpc`'s JSON-Schema
467
537
  * via the `definition` "RunsReadParams".
@@ -515,6 +585,7 @@ export interface CardBlock {
515
585
  [k: string]: string;
516
586
  };
517
587
  origin?: Origin;
588
+ trust?: Trust1;
518
589
  }
519
590
  /**
520
591
  * Where a card came from: the extension, and its channel and thread there.
@@ -527,6 +598,37 @@ export interface Origin {
527
598
  channel: string;
528
599
  thread: string;
529
600
  }
601
+ /**
602
+ * This interface was referenced by `Rpc`'s JSON-Schema
603
+ * via the `definition` "Attachment".
604
+ */
605
+ export interface Attachment {
606
+ id: string;
607
+ name: string;
608
+ url: string;
609
+ bytes?: number;
610
+ }
611
+ /**
612
+ * The answer to `inbox.receive`: `stored` is false when the inbox held the delivery already, so the service handles each delivery once.
613
+ *
614
+ * This interface was referenced by `Rpc`'s JSON-Schema
615
+ * via the `definition` "InboxReceived".
616
+ */
617
+ export interface InboxReceived {
618
+ stored: boolean;
619
+ }
620
+ /**
621
+ * The answer to `inbox.pending`, oldest first.
622
+ *
623
+ * This interface was referenced by `Rpc`'s JSON-Schema
624
+ * via the `definition` "PendingDeliveries".
625
+ */
626
+ export interface PendingDeliveries {
627
+ deliveries: {
628
+ delivery: string;
629
+ payload: string;
630
+ }[];
631
+ }
530
632
  /**
531
633
  * The answer to a move of a service: `applied` is false, with the reason, when the engine refused it.
532
634
  *
@@ -566,6 +668,15 @@ export interface HookCall {
566
668
  role: string;
567
669
  result?: Outcome;
568
670
  }
671
+ /**
672
+ * A card's `edgar:v0` block that does not read, as the tracker says why, so intake refuses the card with that reason instead of working it as plain text.
673
+ *
674
+ * This interface was referenced by `Rpc`'s JSON-Schema
675
+ * via the `definition` "InvalidBlock".
676
+ */
677
+ export interface InvalidBlock {
678
+ invalid: string;
679
+ }
569
680
  /**
570
681
  * This interface was referenced by `Rpc`'s JSON-Schema
571
682
  * via the `definition` "Card".
@@ -577,11 +688,28 @@ export interface Card {
577
688
  column: string;
578
689
  labels: string[];
579
690
  url: string;
580
- block: CardBlock | null;
691
+ block: CardBlock | InvalidBlock | null;
581
692
  /**
582
693
  * Who the card is assigned to, as the tracker names them; absent or null when it is not assigned.
583
694
  */
584
695
  assignee?: string | null;
696
+ /**
697
+ * The person the card is assigned to, as the tracker names them; absent or null when no person holds it, such as a card of nobody or of EDGAR's own user.
698
+ */
699
+ taken_by?: string | null;
700
+ /**
701
+ * A stable id of the person in `taken_by`, which only that person's own account can change, such as their email; the engine finds the person's keys by it, never by a name.
702
+ */
703
+ taken_by_id?: string | null;
704
+ /**
705
+ * The priority a person set on the card in the tracker; absent or null when it is neither urgent nor high. EDGAR never sets it.
706
+ */
707
+ priority?: Priority | null;
708
+ trust?: Trust3;
709
+ /**
710
+ * A stable id of the person who wrote the card, which only their own account can change, such as a login or an email: a person of `[people]` with this id in the tracker is on the team, whatever `trust` says.
711
+ */
712
+ written_by_id?: string;
585
713
  }
586
714
  /**
587
715
  * This interface was referenced by `Rpc`'s JSON-Schema
@@ -596,16 +724,19 @@ export interface Comment {
596
724
  */
597
725
  mentioned?: boolean;
598
726
  at: string;
599
- }
600
- /**
601
- * This interface was referenced by `Rpc`'s JSON-Schema
602
- * via the `definition` "Attachment".
603
- */
604
- export interface Attachment {
605
- id: string;
606
- name: string;
607
- url: string;
608
- bytes?: number;
727
+ /**
728
+ * When the comment was last edited or deleted, for a comment that was.
729
+ */
730
+ edited_at?: string;
731
+ /**
732
+ * True when the comment was deleted, for a tracker that reports deletes.
733
+ */
734
+ deleted?: boolean;
735
+ trust?: Trust4;
736
+ /**
737
+ * A stable id of `author`, as `written_by_id` of a card is.
738
+ */
739
+ author_id?: string;
609
740
  }
610
741
  /**
611
742
  * This interface was referenced by `Rpc`'s JSON-Schema
@@ -639,6 +770,25 @@ export interface ListCardsOutput {
639
770
  export interface CardInput {
640
771
  id: string;
641
772
  }
773
+ /**
774
+ * The comments made after `since` on any card of the tracker that mention EDGAR's account.
775
+ *
776
+ * This interface was referenced by `Rpc`'s JSON-Schema
777
+ * via the `definition` "MentionsInput".
778
+ */
779
+ export interface MentionsInput {
780
+ since: string;
781
+ }
782
+ /**
783
+ * One comment that mentions EDGAR's account, with the card it is on.
784
+ *
785
+ * This interface was referenced by `Rpc`'s JSON-Schema
786
+ * via the `definition` "Mention".
787
+ */
788
+ export interface Mention {
789
+ card: string;
790
+ comment: Comment;
791
+ }
642
792
  /**
643
793
  * This interface was referenced by `Rpc`'s JSON-Schema
644
794
  * via the `definition` "CommentsInput".
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kana-ai/edgar-contracts",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "JSON Schemas of the messages between the EDGAR engine and its TypeScript runtime, with generated types.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {