@kana-ai/edgar-contracts 0.1.3 → 0.1.4
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/README.md +11 -10
- package/dist/manifest.schema.d.ts +11 -0
- package/dist/setup.schema.d.ts +49 -0
- package/package.json +1 -1
- package/schemas/json/manifest.schema.json +18 -0
- package/schemas/json/setup.schema.json +97 -0
package/README.md
CHANGED
|
@@ -4,21 +4,22 @@ JSON Schemas (2020-12) of what the EDGAR engine and its TypeScript side exchange
|
|
|
4
4
|
|
|
5
5
|
Use this package when you write code that reads or writes one of these messages: the SDK, the extension runtime, a provider runtime, or a program that reads `edgar check --json`. An extension author does not import it directly: the SDK gives the same types. For how the processes talk, see [architecture](/docs/concepts/architecture.md#the-processes).
|
|
6
6
|
|
|
7
|
-
> `schemas/json/config.schema.json`, `schemas/json/diagnostic.schema.json` and `schemas/json/
|
|
7
|
+
> `schemas/json/config.schema.json`, `schemas/json/diagnostic.schema.json`, `schemas/json/limit.schema.json` and `schemas/json/setup.schema.json` come from the Rust types `Config`, `Diagnostic`, `Limit` and `Setup`. After you change one of these types, run `edgar contracts emit` from the repository root, and commit the files. A unit test in `edgar-core` fails when a committed file differs. The other four schemas are written by hand until their types derive `JsonSchema`. For them, the files in `schemas/` are the source, and the engine's Rust types in `edgar-core` must match them. See [logs, spans and contracts](/docs/reference/observability.md#make-the-contracts-from-the-rust-types).
|
|
8
8
|
|
|
9
9
|
## Schemas
|
|
10
10
|
|
|
11
11
|
The package has two folders: `schemas/json/` holds the JSON Schema files, and `schemas/ts/` holds the Zod schemas that the TypeScript side imports.
|
|
12
12
|
|
|
13
|
-
| Schema | What it describes
|
|
14
|
-
| ------------------------------------- |
|
|
15
|
-
| `schemas/json/outcome.schema.json` | The outcome union, the temporary and the permanent kinds; `retry_after` is in seconds and `timeout_at` in Unix milliseconds; `done` and both failures take an optional `limit`
|
|
16
|
-
| `schemas/json/limit.schema.json` | One rate or usage limit, `{source, remaining?, limit?, resets_at?, window?}`, made from the Rust `Limit` type by `edgar contracts emit`; `resets_at` is in Unix milliseconds
|
|
17
|
-
| `schemas/json/rpc.schema.json` | The JSON-RPC 2.0 lines between the engine and `edgar-runtime`, their params and results, and the 4 MiB line limit (`MaxMessageBytes`)
|
|
18
|
-
| `schemas/json/provider.schema.json` | The JSON-RPC 2.0 lines between the engine and a provider runtime such as `edgar-provider-claude`: `hello`, `session.*`, `tool.request` and the `session.event` notifications, with the `limit` event
|
|
19
|
-
| `schemas/json/manifest.schema.json` | `edgar-extension.json`, which the SDK build writes
|
|
20
|
-
| `schemas/json/diagnostic.schema.json` | One record of `edgar check --json`
|
|
21
|
-
| `schemas/json/
|
|
13
|
+
| Schema | What it describes |
|
|
14
|
+
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| `schemas/json/outcome.schema.json` | The outcome union, the temporary and the permanent kinds; `retry_after` is in seconds and `timeout_at` in Unix milliseconds; `done` and both failures take an optional `limit` |
|
|
16
|
+
| `schemas/json/limit.schema.json` | One rate or usage limit, `{source, remaining?, limit?, resets_at?, window?}`, made from the Rust `Limit` type by `edgar contracts emit`; `resets_at` is in Unix milliseconds |
|
|
17
|
+
| `schemas/json/rpc.schema.json` | The JSON-RPC 2.0 lines between the engine and `edgar-runtime`, their params and results, and the 4 MiB line limit (`MaxMessageBytes`) |
|
|
18
|
+
| `schemas/json/provider.schema.json` | The JSON-RPC 2.0 lines between the engine and a provider runtime such as `edgar-provider-claude`: `hello`, `session.*`, `tool.request` and the `session.event` notifications, with the `limit` event |
|
|
19
|
+
| `schemas/json/manifest.schema.json` | `edgar-extension.json`, which the SDK build writes |
|
|
20
|
+
| `schemas/json/diagnostic.schema.json` | One record of `edgar check --json` |
|
|
21
|
+
| `schemas/json/setup.schema.json` | What the setup probes found, `{extensions: [{extension, probes: [{label, verdict}]}]}`, each verdict `pass`, `fail` with `reason` and `fix`, or `skipped` with `why`: `edgar check --live --json` prints it under `setup`, and `GET /api/setup` answers it; made from the Rust `Setup` type by `edgar contracts emit` |
|
|
22
|
+
| `schemas/json/config.schema.json` | `edgar.toml`: each key's `title` is its label in the console, its `description` the help sentence, and its `x-edgar` its `group`, its `apply` (`live` or `restart`, once the running project reloads) and its `console` access (`edit` or `view`) |
|
|
22
23
|
|
|
23
24
|
`schemas/ts/` holds the Zod schemas. `end.ts` has `runEnded`, the part of a `run_outcome` event that a note at the end of a run reads. `card.ts` has `cardBlock` and `cardSpec`, whose output types are the `CardBlock` and `CardSpec` of `rpc.schema.json`. The tracker extensions import them from `@kana-ai/edgar-contracts/card`, so their `create_card` schemas stay the same. A card's block has a `kind` (`defect`, `request`, `question` or `investigation`) and optional facts such as `service`, `fingerprint` (16 lower-case hex characters) and `severity`. The intake refuses a card whose block does not match, and says why on the card.
|
|
24
25
|
|
|
@@ -64,6 +64,7 @@ export interface Manifest {
|
|
|
64
64
|
hooks: Hook[];
|
|
65
65
|
service?: Service;
|
|
66
66
|
git_credential?: GitCredential;
|
|
67
|
+
setup?: Setup;
|
|
67
68
|
publish_commits?: PublishCommits;
|
|
68
69
|
identity?: Identity;
|
|
69
70
|
read_link?: ReadLink;
|
|
@@ -211,6 +212,16 @@ export interface GitCredential {
|
|
|
211
212
|
secrets: SecretName[];
|
|
212
213
|
capabilities: Capability[];
|
|
213
214
|
}
|
|
215
|
+
/**
|
|
216
|
+
* What runs `tool.call` of `setup`, the extension's live setup probes, when `edgar check --live`, the console or the MCP tool `setup` asks. The engine calls it with `{ services }`, the project's services, and takes a list of `{ label, verdict }`, each verdict `{ kind: "pass" }`, `{ kind: "fail", reason, fix }` or `{ kind: "skipped", why }`, with every secret hidden. A probe only reads: it reaches no engine port, and its grant holds network hosts only.
|
|
217
|
+
*
|
|
218
|
+
* This interface was referenced by `Manifest`'s JSON-Schema
|
|
219
|
+
* via the `definition` "Setup".
|
|
220
|
+
*/
|
|
221
|
+
export interface Setup {
|
|
222
|
+
secrets: SecretName[];
|
|
223
|
+
capabilities: string[];
|
|
224
|
+
}
|
|
214
225
|
/**
|
|
215
226
|
* 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
227
|
*
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/** Generated by json-schema-to-typescript from the schema of the same name. */
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* What one probe found: it passed, it failed with the reason and the fix, or it was skipped,
|
|
5
|
+
* with why, such as a webhook check on a project that serves no webhook.
|
|
6
|
+
*
|
|
7
|
+
* This interface was referenced by `Setup`'s JSON-Schema
|
|
8
|
+
* via the `definition` "Verdict".
|
|
9
|
+
*/
|
|
10
|
+
export type Verdict =
|
|
11
|
+
| {
|
|
12
|
+
kind: "pass";
|
|
13
|
+
}
|
|
14
|
+
| {
|
|
15
|
+
fix: string;
|
|
16
|
+
kind: "fail";
|
|
17
|
+
reason: string;
|
|
18
|
+
}
|
|
19
|
+
| {
|
|
20
|
+
kind: "skipped";
|
|
21
|
+
why: string;
|
|
22
|
+
};
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* What the setup probes found: `edgar check --live` and the MCP tool `setup`.
|
|
26
|
+
*/
|
|
27
|
+
export interface Setup {
|
|
28
|
+
extensions: ExtensionSetup[];
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* The probes of one extension, in the order it answered them.
|
|
32
|
+
*
|
|
33
|
+
* This interface was referenced by `Setup`'s JSON-Schema
|
|
34
|
+
* via the `definition` "ExtensionSetup".
|
|
35
|
+
*/
|
|
36
|
+
export interface ExtensionSetup {
|
|
37
|
+
extension: string;
|
|
38
|
+
probes: Probe[];
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* One probe: what it checks, such as "the token reads acme/api", and what it found.
|
|
42
|
+
*
|
|
43
|
+
* This interface was referenced by `Setup`'s JSON-Schema
|
|
44
|
+
* via the `definition` "Probe".
|
|
45
|
+
*/
|
|
46
|
+
export interface Probe {
|
|
47
|
+
label: string;
|
|
48
|
+
verdict: Verdict;
|
|
49
|
+
}
|
package/package.json
CHANGED
|
@@ -20,6 +20,7 @@
|
|
|
20
20
|
"hooks": { "type": "array", "items": { "$ref": "#/$defs/Hook" } },
|
|
21
21
|
"service": { "$ref": "#/$defs/Service" },
|
|
22
22
|
"git_credential": { "$ref": "#/$defs/GitCredential" },
|
|
23
|
+
"setup": { "$ref": "#/$defs/Setup" },
|
|
23
24
|
"publish_commits": { "$ref": "#/$defs/PublishCommits" },
|
|
24
25
|
"identity": { "$ref": "#/$defs/Identity" },
|
|
25
26
|
"read_link": { "$ref": "#/$defs/ReadLink" },
|
|
@@ -225,6 +226,23 @@
|
|
|
225
226
|
"required": ["secrets", "capabilities"],
|
|
226
227
|
"additionalProperties": false
|
|
227
228
|
},
|
|
229
|
+
"Setup": {
|
|
230
|
+
"title": "Setup",
|
|
231
|
+
"description": "What runs `tool.call` of `setup`, the extension's live setup probes, when `edgar check --live`, the console or the MCP tool `setup` asks. The engine calls it with `{ services }`, the project's services, and takes a list of `{ label, verdict }`, each verdict `{ kind: \"pass\" }`, `{ kind: \"fail\", reason, fix }` or `{ kind: \"skipped\", why }`, with every secret hidden. A probe only reads: it reaches no engine port, and its grant holds network hosts only.",
|
|
232
|
+
"type": "object",
|
|
233
|
+
"properties": {
|
|
234
|
+
"secrets": { "type": "array", "items": { "$ref": "#/$defs/SecretName" } },
|
|
235
|
+
"capabilities": {
|
|
236
|
+
"type": "array",
|
|
237
|
+
"items": {
|
|
238
|
+
"type": "string",
|
|
239
|
+
"pattern": "^network:(\\*\\.)?[a-z0-9]([a-z0-9.-]*[a-z0-9])?$"
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
},
|
|
243
|
+
"required": ["secrets", "capabilities"],
|
|
244
|
+
"additionalProperties": false
|
|
245
|
+
},
|
|
228
246
|
"PublishCommits": {
|
|
229
247
|
"title": "PublishCommits",
|
|
230
248
|
"description": "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.",
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$defs": {
|
|
3
|
+
"ExtensionSetup": {
|
|
4
|
+
"additionalProperties": false,
|
|
5
|
+
"description": "The probes of one extension, in the order it answered them.",
|
|
6
|
+
"properties": {
|
|
7
|
+
"extension": {
|
|
8
|
+
"type": "string"
|
|
9
|
+
},
|
|
10
|
+
"probes": {
|
|
11
|
+
"items": {
|
|
12
|
+
"$ref": "#/$defs/Probe"
|
|
13
|
+
},
|
|
14
|
+
"type": "array"
|
|
15
|
+
}
|
|
16
|
+
},
|
|
17
|
+
"required": ["extension", "probes"],
|
|
18
|
+
"type": "object"
|
|
19
|
+
},
|
|
20
|
+
"Probe": {
|
|
21
|
+
"additionalProperties": false,
|
|
22
|
+
"description": "One probe: what it checks, such as \"the token reads acme/api\", and what it found.",
|
|
23
|
+
"properties": {
|
|
24
|
+
"label": {
|
|
25
|
+
"minLength": 1,
|
|
26
|
+
"type": "string"
|
|
27
|
+
},
|
|
28
|
+
"verdict": {
|
|
29
|
+
"$ref": "#/$defs/Verdict"
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
"required": ["label", "verdict"],
|
|
33
|
+
"type": "object"
|
|
34
|
+
},
|
|
35
|
+
"Verdict": {
|
|
36
|
+
"description": "What one probe found: it passed, it failed with the reason and the fix, or it was skipped,\nwith why, such as a webhook check on a project that serves no webhook.",
|
|
37
|
+
"oneOf": [
|
|
38
|
+
{
|
|
39
|
+
"additionalProperties": false,
|
|
40
|
+
"properties": {
|
|
41
|
+
"kind": {
|
|
42
|
+
"const": "pass",
|
|
43
|
+
"type": "string"
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
"required": ["kind"],
|
|
47
|
+
"type": "object"
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
"additionalProperties": false,
|
|
51
|
+
"properties": {
|
|
52
|
+
"fix": {
|
|
53
|
+
"type": "string"
|
|
54
|
+
},
|
|
55
|
+
"kind": {
|
|
56
|
+
"const": "fail",
|
|
57
|
+
"type": "string"
|
|
58
|
+
},
|
|
59
|
+
"reason": {
|
|
60
|
+
"type": "string"
|
|
61
|
+
}
|
|
62
|
+
},
|
|
63
|
+
"required": ["kind", "reason", "fix"],
|
|
64
|
+
"type": "object"
|
|
65
|
+
},
|
|
66
|
+
{
|
|
67
|
+
"additionalProperties": false,
|
|
68
|
+
"properties": {
|
|
69
|
+
"kind": {
|
|
70
|
+
"const": "skipped",
|
|
71
|
+
"type": "string"
|
|
72
|
+
},
|
|
73
|
+
"why": {
|
|
74
|
+
"type": "string"
|
|
75
|
+
}
|
|
76
|
+
},
|
|
77
|
+
"required": ["kind", "why"],
|
|
78
|
+
"type": "object"
|
|
79
|
+
}
|
|
80
|
+
]
|
|
81
|
+
}
|
|
82
|
+
},
|
|
83
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
84
|
+
"additionalProperties": false,
|
|
85
|
+
"description": "What the setup probes found: `edgar check --live` and the MCP tool `setup`.",
|
|
86
|
+
"properties": {
|
|
87
|
+
"extensions": {
|
|
88
|
+
"items": {
|
|
89
|
+
"$ref": "#/$defs/ExtensionSetup"
|
|
90
|
+
},
|
|
91
|
+
"type": "array"
|
|
92
|
+
}
|
|
93
|
+
},
|
|
94
|
+
"required": ["extensions"],
|
|
95
|
+
"title": "Setup",
|
|
96
|
+
"type": "object"
|
|
97
|
+
}
|