@kana-ai/edgar-sdk 0.0.0-stage → 0.1.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/LICENSE +202 -0
- package/README.md +430 -2
- package/dist/src/build/cli.d.ts +6 -0
- package/dist/src/build/cli.js +110 -0
- package/dist/src/build/json.d.ts +2 -0
- package/dist/src/build/json.js +71 -0
- package/dist/src/build/manifest.d.ts +15 -0
- package/dist/src/build/manifest.js +111 -0
- package/dist/src/define/card-block.d.ts +15 -0
- package/dist/src/define/card-block.js +66 -0
- package/dist/src/define/context.d.ts +60 -0
- package/dist/src/define/context.js +1 -0
- package/dist/src/define/extension.d.ts +58 -0
- package/dist/src/define/extension.js +14 -0
- package/dist/src/define/hook.d.ts +61 -0
- package/dist/src/define/hook.js +72 -0
- package/dist/src/define/service.d.ts +32 -0
- package/dist/src/define/service.js +33 -0
- package/dist/src/define/tool.d.ts +93 -0
- package/dist/src/define/tool.js +24 -0
- package/dist/src/define/tracker.d.ts +59 -0
- package/dist/src/define/tracker.js +27 -0
- package/dist/src/index.d.ts +15 -0
- package/dist/src/index.js +12 -0
- package/dist/src/outcome/end.d.ts +61 -0
- package/dist/src/outcome/end.js +292 -0
- package/dist/src/outcome/failures.d.ts +15 -0
- package/dist/src/outcome/failures.js +57 -0
- package/dist/src/outcome/limits.d.ts +13 -0
- package/dist/src/outcome/limits.js +115 -0
- package/dist/src/outcome/outcome.d.ts +32 -0
- package/dist/src/outcome/outcome.js +59 -0
- package/dist/src/outcome/plain.d.ts +7 -0
- package/dist/src/outcome/plain.js +55 -0
- package/dist/src/outcome/result.d.ts +35 -0
- package/dist/src/outcome/result.js +58 -0
- package/dist/src/provider/child.d.ts +51 -0
- package/dist/src/provider/child.js +152 -0
- package/dist/src/provider/serve.d.ts +42 -0
- package/dist/src/provider/serve.js +175 -0
- package/dist/src/runtime/index.d.ts +4 -0
- package/dist/src/runtime/index.js +3 -0
- package/dist/src/runtime/invoke.d.ts +10 -0
- package/dist/src/runtime/invoke.js +232 -0
- package/dist/src/runtime/network.d.ts +20 -0
- package/dist/src/runtime/network.js +120 -0
- package/dist/src/runtime/ports.d.ts +31 -0
- package/dist/src/runtime/ports.js +1 -0
- package/dist/src/runtime/secrets.d.ts +13 -0
- package/dist/src/runtime/secrets.js +33 -0
- package/dist/src/testing/context.d.ts +12 -0
- package/dist/src/testing/context.js +39 -0
- package/dist/src/testing/index.d.ts +3 -0
- package/dist/src/testing/index.js +3 -0
- package/dist/src/testing/mock.d.ts +16 -0
- package/dist/src/testing/mock.js +39 -0
- package/dist/src/wire/codec.d.ts +46 -0
- package/dist/src/wire/codec.js +134 -0
- package/dist/src/wire/lines.d.ts +10 -0
- package/dist/src/wire/lines.js +41 -0
- package/package.json +48 -3
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import type { Capability as ManifestCapability } from "@kana-ai/edgar-contracts/manifest";
|
|
2
|
+
import type { ApprovalDecision } from "@kana-ai/edgar-contracts/rpc";
|
|
3
|
+
import type { Ctx } from "#define/context";
|
|
4
|
+
import type { Outcome } from "#outcome/outcome";
|
|
5
|
+
declare const toolBrand: unique symbol;
|
|
6
|
+
/** One problem a Standard Schema `validate` reports, at the path of the value it concerns. */
|
|
7
|
+
export interface Issue {
|
|
8
|
+
readonly message: string;
|
|
9
|
+
readonly path?: readonly (PropertyKey | {
|
|
10
|
+
readonly key: PropertyKey;
|
|
11
|
+
})[] | undefined;
|
|
12
|
+
}
|
|
13
|
+
/** What a Standard Schema `validate` answers: the value, or the issues. */
|
|
14
|
+
export type Validation = {
|
|
15
|
+
readonly value: unknown;
|
|
16
|
+
readonly issues?: undefined;
|
|
17
|
+
} | {
|
|
18
|
+
readonly issues: readonly Issue[];
|
|
19
|
+
};
|
|
20
|
+
/** A schema the build turns into JSON Schema 2020-12: a Zod 4 schema or the value of `jsonSchema()`; only the first has `validate`. */
|
|
21
|
+
export interface Schema<I = unknown> {
|
|
22
|
+
readonly "~standard": {
|
|
23
|
+
readonly version: 1;
|
|
24
|
+
readonly vendor: string;
|
|
25
|
+
readonly validate?: (value: unknown) => Validation | Promise<Validation>;
|
|
26
|
+
readonly types?: {
|
|
27
|
+
readonly input: I;
|
|
28
|
+
readonly output: unknown;
|
|
29
|
+
} | undefined;
|
|
30
|
+
readonly jsonSchema: {
|
|
31
|
+
readonly input: (options: {
|
|
32
|
+
readonly target: "draft-2020-12";
|
|
33
|
+
}) => Record<string, unknown>;
|
|
34
|
+
readonly output: (options: {
|
|
35
|
+
readonly target: "draft-2020-12";
|
|
36
|
+
}) => Record<string, unknown>;
|
|
37
|
+
};
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
/** The JSON value a schema accepts, which is what the engine validates and hands over. */
|
|
41
|
+
export type In<S extends Schema> = NonNullable<S["~standard"]["types"]>["input"];
|
|
42
|
+
/** Wraps a plain JSON Schema 2020-12 object; `T` is the type the author promises it describes. */
|
|
43
|
+
export declare function jsonSchema<T>(schema: Readonly<Record<string, unknown>>): Schema<T>;
|
|
44
|
+
/** The closed set of capabilities an extension may declare, within the manifest's `Capability`. */
|
|
45
|
+
export type Capability = ManifestCapability & (`network:${string}` | "sandbox:read" | "sandbox:write" | "git:push" | "tracker:read" | "tracker:write" | "runs:read" | "complete");
|
|
46
|
+
/** Who may run a call: `never`, `once` per run, `always`, or `auto`, a function that may only tighten. */
|
|
47
|
+
export type Approval<I> = "never" | "once" | "always" | {
|
|
48
|
+
auto(input: I, ctx: Ctx<string>): Promise<ApprovalDecision>;
|
|
49
|
+
};
|
|
50
|
+
/** A side effect names its undo pair, or says why it has none. */
|
|
51
|
+
export type SideEffect = {
|
|
52
|
+
readonly side_effect?: false;
|
|
53
|
+
} | {
|
|
54
|
+
readonly side_effect: true;
|
|
55
|
+
readonly compensate: string;
|
|
56
|
+
readonly lookup: string;
|
|
57
|
+
} | {
|
|
58
|
+
readonly side_effect: true;
|
|
59
|
+
readonly undo: "none";
|
|
60
|
+
readonly undo_reason: string;
|
|
61
|
+
};
|
|
62
|
+
/** What `defineTool` takes; `output` is required, so a tool without an output schema does not compile. */
|
|
63
|
+
export type ToolSpec<IS extends Schema, OS extends Schema, S extends string> = {
|
|
64
|
+
readonly description: string;
|
|
65
|
+
readonly input: IS;
|
|
66
|
+
readonly output: OS;
|
|
67
|
+
readonly secrets?: readonly S[];
|
|
68
|
+
readonly capabilities?: readonly Capability[];
|
|
69
|
+
readonly approval?: Approval<In<IS>>;
|
|
70
|
+
readonly execute: (input: In<IS>, ctx: Ctx<S>) => Promise<Outcome<NoInfer<In<OS>>>>;
|
|
71
|
+
} & SideEffect;
|
|
72
|
+
/** A tool value; only `defineTool` makes one. */
|
|
73
|
+
export interface Tool<I = unknown, O = unknown, S extends string = string> {
|
|
74
|
+
readonly [toolBrand]: true;
|
|
75
|
+
readonly description: string;
|
|
76
|
+
readonly input: Schema;
|
|
77
|
+
readonly output: Schema;
|
|
78
|
+
readonly secrets: readonly string[];
|
|
79
|
+
readonly capabilities: readonly Capability[];
|
|
80
|
+
readonly approval: Approval<I>;
|
|
81
|
+
readonly side_effect: boolean;
|
|
82
|
+
readonly compensate?: string;
|
|
83
|
+
readonly lookup?: string;
|
|
84
|
+
readonly undo?: "none";
|
|
85
|
+
readonly undo_reason?: string;
|
|
86
|
+
readonly disabled: boolean;
|
|
87
|
+
execute(input: I, ctx: Ctx<S>): Promise<Outcome<O>>;
|
|
88
|
+
}
|
|
89
|
+
/** Defines a tool; the name is its key in `defineExtension({ tools })`. */
|
|
90
|
+
export declare function defineTool<IS extends Schema, OS extends Schema, const S extends string = never>(spec: ToolSpec<IS, OS, S>): Tool<In<IS>, In<OS>, S>;
|
|
91
|
+
/** Ships a tool off; a project turns it on in `edgar.toml`. */
|
|
92
|
+
export declare function disableTool<I, O, S extends string>(tool: Tool<I, O, S>): Tool<I, O, S>;
|
|
93
|
+
export {};
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
const toolBrand = Symbol.for("edgar.sdk.tool");
|
|
2
|
+
/** Wraps a plain JSON Schema 2020-12 object; `T` is the type the author promises it describes. */
|
|
3
|
+
export function jsonSchema(schema) {
|
|
4
|
+
const emit = () => ({ ...schema });
|
|
5
|
+
return {
|
|
6
|
+
"~standard": { version: 1, vendor: "edgar", jsonSchema: { input: emit, output: emit } },
|
|
7
|
+
};
|
|
8
|
+
}
|
|
9
|
+
/** Defines a tool; the name is its key in `defineExtension({ tools })`. */
|
|
10
|
+
export function defineTool(spec) {
|
|
11
|
+
return {
|
|
12
|
+
...spec,
|
|
13
|
+
[toolBrand]: true,
|
|
14
|
+
secrets: spec.secrets ?? [],
|
|
15
|
+
capabilities: spec.capabilities ?? [],
|
|
16
|
+
approval: spec.approval ?? "never",
|
|
17
|
+
side_effect: spec.side_effect ?? false,
|
|
18
|
+
disabled: false,
|
|
19
|
+
};
|
|
20
|
+
}
|
|
21
|
+
/** Ships a tool off; a project turns it on in `edgar.toml`. */
|
|
22
|
+
export function disableTool(tool) {
|
|
23
|
+
return { ...tool, disabled: true };
|
|
24
|
+
}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import type { TrackerMethod as ManifestTrackerMethod } from "@kana-ai/edgar-contracts/manifest";
|
|
2
|
+
import type { Actor, Attachment, Card, CardInput, CloseInput, Comment, CommentInput, CommentsInput, Created, CreateCardInput, ListCardsInput, ListCardsOutput, MoveInput, Person, PersonInput, SetLabelsInput } from "@kana-ai/edgar-contracts/rpc";
|
|
3
|
+
import type { Ctx, PortResult } from "#define/context";
|
|
4
|
+
import type { Capability } from "#define/tool";
|
|
5
|
+
import type { Outcome } from "#outcome/outcome";
|
|
6
|
+
declare const trackerBrand: unique symbol;
|
|
7
|
+
/** Input and output of each tracker port method. */
|
|
8
|
+
export interface TrackerTypes {
|
|
9
|
+
readonly list_cards: readonly [ListCardsInput, ListCardsOutput];
|
|
10
|
+
/** `not_found` for a card that is archived or deleted: the engine reads a card that a listing no longer has to learn if it left. */
|
|
11
|
+
readonly card: readonly [CardInput, Card];
|
|
12
|
+
readonly comments: readonly [CommentsInput, Comment[]];
|
|
13
|
+
readonly attachments: readonly [CardInput, Attachment[]];
|
|
14
|
+
readonly comment: readonly [CommentInput, Created];
|
|
15
|
+
readonly move: readonly [MoveInput, null];
|
|
16
|
+
readonly set_labels: readonly [SetLabelsInput, null];
|
|
17
|
+
readonly create_card: readonly [CreateCardInput, Created];
|
|
18
|
+
readonly close: readonly [CloseInput, null];
|
|
19
|
+
readonly whoami: readonly [Readonly<Record<string, never>>, Actor];
|
|
20
|
+
readonly person: readonly [PersonInput, Person];
|
|
21
|
+
}
|
|
22
|
+
/** Any input and output per tracker port method. */
|
|
23
|
+
export type TrackerIO = {
|
|
24
|
+
readonly [M in TrackerMethod]: readonly [unknown, unknown];
|
|
25
|
+
};
|
|
26
|
+
/** A tracker port method name; equal to the manifest's list. */
|
|
27
|
+
export type TrackerMethod = keyof TrackerTypes & ManifestTrackerMethod;
|
|
28
|
+
/** Every tracker port method, in the manifest's order. */
|
|
29
|
+
export declare const trackerMethods: readonly ["list_cards", "card", "comments", "attachments", "comment", "move", "set_labels", "create_card", "close", "whoami", "person"];
|
|
30
|
+
/** The engine's tracker port as a tool sees it, gated by `tracker:read` and `tracker:write`. */
|
|
31
|
+
export type TrackerPort = {
|
|
32
|
+
readonly [M in TrackerMethod]: (input: TrackerTypes[M][0]) => Promise<PortResult<Outcome<TrackerTypes[M][1]>>>;
|
|
33
|
+
};
|
|
34
|
+
/** What `defineTracker` takes: every method of the tracker port. */
|
|
35
|
+
export interface TrackerSpec<S extends string, T extends TrackerIO = TrackerTypes> {
|
|
36
|
+
readonly secrets?: readonly S[];
|
|
37
|
+
readonly capabilities?: readonly Capability[];
|
|
38
|
+
list_cards(input: T["list_cards"][0], ctx: Ctx<S>): Promise<Outcome<T["list_cards"][1]>>;
|
|
39
|
+
card(input: T["card"][0], ctx: Ctx<S>): Promise<Outcome<T["card"][1]>>;
|
|
40
|
+
comments(input: T["comments"][0], ctx: Ctx<S>): Promise<Outcome<T["comments"][1]>>;
|
|
41
|
+
attachments(input: T["attachments"][0], ctx: Ctx<S>): Promise<Outcome<T["attachments"][1]>>;
|
|
42
|
+
comment(input: T["comment"][0], ctx: Ctx<S>): Promise<Outcome<T["comment"][1]>>;
|
|
43
|
+
move(input: T["move"][0], ctx: Ctx<S>): Promise<Outcome<T["move"][1]>>;
|
|
44
|
+
set_labels(input: T["set_labels"][0], ctx: Ctx<S>): Promise<Outcome<T["set_labels"][1]>>;
|
|
45
|
+
create_card(input: T["create_card"][0], ctx: Ctx<S>): Promise<Outcome<T["create_card"][1]>>;
|
|
46
|
+
close(input: T["close"][0], ctx: Ctx<S>): Promise<Outcome<T["close"][1]>>;
|
|
47
|
+
whoami(input: T["whoami"][0], ctx: Ctx<S>): Promise<Outcome<T["whoami"][1]>>;
|
|
48
|
+
person(input: T["person"][0], ctx: Ctx<S>): Promise<Outcome<T["person"][1]>>;
|
|
49
|
+
}
|
|
50
|
+
/** A tracker value; only `defineTracker` makes one. */
|
|
51
|
+
export interface Tracker {
|
|
52
|
+
readonly [trackerBrand]: true;
|
|
53
|
+
readonly secrets: readonly string[];
|
|
54
|
+
readonly capabilities: readonly Capability[];
|
|
55
|
+
call(method: TrackerMethod, input: unknown, ctx: Ctx<string>): Promise<Outcome>;
|
|
56
|
+
}
|
|
57
|
+
/** Defines the tracker port of an extension. A project can enable more than one tracker; each card goes through its own. */
|
|
58
|
+
export declare function defineTracker<const S extends string = never>(spec: TrackerSpec<S>): Tracker;
|
|
59
|
+
export {};
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
const trackerBrand = Symbol.for("edgar.sdk.tracker");
|
|
2
|
+
/** Every tracker port method, in the manifest's order. */
|
|
3
|
+
export const trackerMethods = [
|
|
4
|
+
"list_cards",
|
|
5
|
+
"card",
|
|
6
|
+
"comments",
|
|
7
|
+
"attachments",
|
|
8
|
+
"comment",
|
|
9
|
+
"move",
|
|
10
|
+
"set_labels",
|
|
11
|
+
"create_card",
|
|
12
|
+
"close",
|
|
13
|
+
"whoami",
|
|
14
|
+
"person",
|
|
15
|
+
];
|
|
16
|
+
/** Defines the tracker port of an extension. A project can enable more than one tracker; each card goes through its own. */
|
|
17
|
+
export function defineTracker(spec) {
|
|
18
|
+
return {
|
|
19
|
+
[trackerBrand]: true,
|
|
20
|
+
secrets: spec.secrets ?? [],
|
|
21
|
+
capabilities: spec.capabilities ?? [],
|
|
22
|
+
async call(method, input, ctx) {
|
|
23
|
+
const erased = spec;
|
|
24
|
+
return await erased[method](input, ctx);
|
|
25
|
+
},
|
|
26
|
+
};
|
|
27
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
export type { PermanentFailure, PermanentKind, Skipped, TemporaryFailure, TemporaryKind, Waiting, } from "@kana-ai/edgar-contracts/outcome";
|
|
2
|
+
export type { FailureKind } from "@kana-ai/edgar-contracts/provider";
|
|
3
|
+
export type { HookCall, HookDecision } from "@kana-ai/edgar-contracts/rpc";
|
|
4
|
+
export * from "#define/card-block";
|
|
5
|
+
export * from "#define/context";
|
|
6
|
+
export * from "#define/extension";
|
|
7
|
+
export * from "#define/hook";
|
|
8
|
+
export * from "#define/service";
|
|
9
|
+
export * from "#define/tool";
|
|
10
|
+
export * from "#define/tracker";
|
|
11
|
+
export * from "#outcome/end";
|
|
12
|
+
export * from "#outcome/failures";
|
|
13
|
+
export { type Limit, type LimitScheme, limitFromHeaders, reportLimit } from "#outcome/limits";
|
|
14
|
+
export * from "#outcome/outcome";
|
|
15
|
+
export * from "#outcome/result";
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export * from "#define/card-block";
|
|
2
|
+
export * from "#define/context";
|
|
3
|
+
export * from "#define/extension";
|
|
4
|
+
export * from "#define/hook";
|
|
5
|
+
export * from "#define/service";
|
|
6
|
+
export * from "#define/tool";
|
|
7
|
+
export * from "#define/tracker";
|
|
8
|
+
export * from "#outcome/end";
|
|
9
|
+
export * from "#outcome/failures";
|
|
10
|
+
export { limitFromHeaders, reportLimit } from "#outcome/limits";
|
|
11
|
+
export * from "#outcome/outcome";
|
|
12
|
+
export * from "#outcome/result";
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { type RunCard } from "@kana-ai/edgar-contracts/end";
|
|
2
|
+
import type { RunEvent } from "#define/hook";
|
|
3
|
+
export { runCard } from "@kana-ai/edgar-contracts/end";
|
|
4
|
+
/** How a medium writes an end note: a link with its label, and a text that came from a card, a model or a failure made safe for the medium. `link` makes its own label safe. */
|
|
5
|
+
export interface NoteStyle {
|
|
6
|
+
link(url: string, label: string): string;
|
|
7
|
+
text(text: string): string;
|
|
8
|
+
/** The sentence that says where a person answers a decision; with none, the note says on the card. */
|
|
9
|
+
readonly reply?: string;
|
|
10
|
+
}
|
|
11
|
+
/** The card of an end note: its link and title, and its id and service when the run names them. */
|
|
12
|
+
export interface NoteCard {
|
|
13
|
+
readonly url: string;
|
|
14
|
+
readonly title: string;
|
|
15
|
+
readonly id?: string;
|
|
16
|
+
readonly service?: string;
|
|
17
|
+
}
|
|
18
|
+
/** A pull request of an end note: its address, its label, such as `api#12`, and `referenced` when the run did not open it but worked on it or found it. */
|
|
19
|
+
export interface NotePull {
|
|
20
|
+
readonly url: string;
|
|
21
|
+
readonly label: string;
|
|
22
|
+
readonly referenced?: true;
|
|
23
|
+
}
|
|
24
|
+
/** The facts of an end note as plain text that no style changed, for a medium that lays the note out by itself: the run and what it used (`took` is the time from the start of this run to its end, with each wait in it, and `tokens` is left out for a run with no model token), the address of the run's page when the console has one, each pull request that the note names, who approved it and the first 7 characters of its merge commit when people decided on it, the sentence on the merge risk, the summary and the options of the newest proposal, or the question that the run ends on when it asks a person for their call, and for a failed run its stage, its message as the engine wrote it, and that message in plain words (`why`) when it starts with a known failure word or the run's outcome has a known failure kind. A step that the engine stopped trying after too many uncharged tries also has `next`, what a person checks before a replay. */
|
|
25
|
+
export interface NoteFacts {
|
|
26
|
+
readonly run: string;
|
|
27
|
+
readonly took?: string;
|
|
28
|
+
readonly tokens?: string;
|
|
29
|
+
readonly cost?: string;
|
|
30
|
+
readonly page?: string;
|
|
31
|
+
readonly workflow?: string;
|
|
32
|
+
readonly pulls: readonly NotePull[];
|
|
33
|
+
readonly approvedBy?: readonly string[];
|
|
34
|
+
readonly commit?: string;
|
|
35
|
+
readonly risk?: string;
|
|
36
|
+
readonly summary?: string;
|
|
37
|
+
readonly options: readonly string[];
|
|
38
|
+
readonly stage?: string;
|
|
39
|
+
readonly failure?: string;
|
|
40
|
+
readonly why?: string;
|
|
41
|
+
readonly next?: string;
|
|
42
|
+
readonly failedBefore: number;
|
|
43
|
+
}
|
|
44
|
+
/** What an end note says: `what` is the one thing a person must know (the run opened a pull request that waits for a review, its pull request is merged, is approved and still open, got a change request or was closed with no merge, the run needs a decision, waits on something before it can go on, failed, was stopped, is done, or is the first run of its schedule that works again), `outcome` is the run's outcome as the engine names it, `card` is the run's card, and `lines` are the note. `assignee` is the person the card is assigned to, as the card names them; when it is set, the first of `lines` is the line that names them, so a medium that can mention a person writes that line again. `repeat` marks a failed run of a schedule whose run just before it failed the same way: the note tells a person nothing new, so a sender leaves it out. `facts` are the same note as plain values. */
|
|
45
|
+
export interface EndNote {
|
|
46
|
+
readonly what: "opened" | "merged" | "approved" | "changes" | "closed" | "decision" | "waits" | "failed" | "stopped" | "done" | "recovered";
|
|
47
|
+
readonly repeat: boolean;
|
|
48
|
+
readonly outcome: string;
|
|
49
|
+
readonly card: NoteCard | undefined;
|
|
50
|
+
readonly assignee?: string;
|
|
51
|
+
readonly lines: readonly string[];
|
|
52
|
+
readonly facts: NoteFacts;
|
|
53
|
+
}
|
|
54
|
+
/** A pull request as a note names it: its address when that is an `http` or `https` address, with the label `<repository>#<number>`, and `referenced` when the run did not open it. None for any other address. */
|
|
55
|
+
export declare function notePull(url: string, number: number, referenced?: boolean): NotePull | undefined;
|
|
56
|
+
/** The card that a `run_created` payload or an end record names, when it has a link. */
|
|
57
|
+
export declare function noteCard(run: RunCard | undefined): NoteCard | undefined;
|
|
58
|
+
/** A card as a line: its id as the link, then its service and title, or its title as the link when the run names no id. */
|
|
59
|
+
export declare function cardLine(card: NoteCard, style: NoteStyle): string;
|
|
60
|
+
/** The end note of a `run_outcome` event in a medium's `style`: who the card is assigned to, the card, what EDGAR did, and what the run used, with a link to the run's page when `consoleUrl` is given. A payload whose `end` or `totals` does not read gives the note of its `outcome` alone, so the note still says whether the run finished. `undefined` for any other event, and for a payload whose `outcome` does not read. */
|
|
61
|
+
export declare function endNote(event: RunEvent, style: NoteStyle, consoleUrl?: string): EndNote | undefined;
|
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
import { runEnded } from "@kana-ai/edgar-contracts/end";
|
|
2
|
+
import { plainFailure, plainLimit } from "#outcome/plain";
|
|
3
|
+
export { runCard } from "@kana-ai/edgar-contracts/end";
|
|
4
|
+
/** A style that changes nothing, for the plain values of `NoteFacts`. */
|
|
5
|
+
const asIs = { link: (_url, label) => label, text: (text) => text };
|
|
6
|
+
const MAX_WORDS = 25;
|
|
7
|
+
/** The most characters of a proposal's summary that a decision note shows. A person decides from it, so it is not cut to one sentence. */
|
|
8
|
+
const MAX_DECISION_CHARS = 1200;
|
|
9
|
+
/** The question a run ends on, when no escalation or handoff already asks a person for their decision. */
|
|
10
|
+
function asked(end) {
|
|
11
|
+
if (end?.decision === "escalate" || end?.decision === "handoff")
|
|
12
|
+
return undefined;
|
|
13
|
+
return end?.question?.trim() === "" ? undefined : end?.question;
|
|
14
|
+
}
|
|
15
|
+
/** The summary of a decision as one paragraph of at most `MAX_DECISION_CHARS` characters. */
|
|
16
|
+
function whole(summary, style) {
|
|
17
|
+
const text = summary.trim().replaceAll(/\s+/g, " ");
|
|
18
|
+
return style.text(text.length > MAX_DECISION_CHARS ? `${text.slice(0, MAX_DECISION_CHARS)}…` : text);
|
|
19
|
+
}
|
|
20
|
+
/** `head` and the first sentence of the first line of `text` as one sentence of at most `MAX_WORDS` words, cut with an ellipsis. A sentence ends where the next word starts with a capital letter, so "e.g." does not end one. With no text, `head` alone with no colon. */
|
|
21
|
+
function sentence(head, text, style) {
|
|
22
|
+
const line = text?.trim().split("\n")[0] ?? "";
|
|
23
|
+
const said = (line.split(/(?<=[.!?])\s+(?=\p{Lu})/u)[0] ?? "").trim().replace(/[.!?:;,]+$/, "");
|
|
24
|
+
if (said === "")
|
|
25
|
+
return head.replace(/:$/, ".");
|
|
26
|
+
const words = `${head} ${said}`.split(/\s+/).filter((word) => word !== "");
|
|
27
|
+
const cut = words.length > MAX_WORDS;
|
|
28
|
+
return `${style.text(words.slice(0, MAX_WORDS).join(" "))}${cut ? "…" : "."}`;
|
|
29
|
+
}
|
|
30
|
+
/** A pull request as a note names it: its address when that is an `http` or `https` address, with the label `<repository>#<number>`, and `referenced` when the run did not open it. None for any other address. */
|
|
31
|
+
export function notePull(url, number, referenced = false) {
|
|
32
|
+
if (!/^https?:\/\//.test(url))
|
|
33
|
+
return undefined;
|
|
34
|
+
const repository = /^https?:\/\/[^/]+\/[^/]+\/([^/]+)\/pull\//.exec(url)?.[1] ?? "";
|
|
35
|
+
const label = `${repository}#${String(number)}`;
|
|
36
|
+
return referenced ? { url, label, referenced } : { url, label };
|
|
37
|
+
}
|
|
38
|
+
/** Each pull request of a run that `notePull` names. */
|
|
39
|
+
function pullsOf(end) {
|
|
40
|
+
return (end?.pull_requests ?? []).flatMap(({ url, number, referenced }) => notePull(url, number, referenced === true) ?? []);
|
|
41
|
+
}
|
|
42
|
+
/** The sentence on the review's merge risk and its reason, when the risk is one word above `low`; else nothing. */
|
|
43
|
+
function riskOf(end, style) {
|
|
44
|
+
const risk = end?.risk?.trim().toLowerCase() ?? "";
|
|
45
|
+
return !/^[a-z]+$/.test(risk) || risk === "low"
|
|
46
|
+
? []
|
|
47
|
+
: [sentence(`The merge risk is ${risk}:`, end?.risk_reason, style)];
|
|
48
|
+
}
|
|
49
|
+
/** What people decided on the run's pull request, when its stages read a decision: `merged` and `closed` are the state of the pull request, and an open one is `approved` or has `changes` asked. None while no review has decided, and none for a run with no card, such as a schedule that reads each pull request at each slot. */
|
|
50
|
+
function reviewOf(end) {
|
|
51
|
+
if (end?.card_url === undefined)
|
|
52
|
+
return undefined;
|
|
53
|
+
const { state, review_state } = end.reviewed ?? {};
|
|
54
|
+
if (state === "merged" || state === "closed")
|
|
55
|
+
return state;
|
|
56
|
+
if (review_state === "approved")
|
|
57
|
+
return "approved";
|
|
58
|
+
return review_state === "changes_requested" ? "changes" : undefined;
|
|
59
|
+
}
|
|
60
|
+
/** "ana", "ana and bo", "ana, bo and cy". */
|
|
61
|
+
function namesOf(names) {
|
|
62
|
+
return names.length < 2
|
|
63
|
+
? names.join("")
|
|
64
|
+
: `${names.slice(0, -1).join(", ")} and ${names.at(-1) ?? ""}`;
|
|
65
|
+
}
|
|
66
|
+
/** The first sentence of the note of each decision on a pull request. */
|
|
67
|
+
const REVIEWED = {
|
|
68
|
+
merged: "The pull request is merged",
|
|
69
|
+
approved: "The pull request is approved and not merged yet",
|
|
70
|
+
changes: "A reviewer asked for changes on the pull request",
|
|
71
|
+
closed: "The pull request was closed with no merge",
|
|
72
|
+
};
|
|
73
|
+
/** The first 7 characters of the merge commit of a merged pull request. */
|
|
74
|
+
function mergeOf(end) {
|
|
75
|
+
return reviewOf(end) === "merged" ? end?.reviewed?.commit?.slice(0, 7) : undefined;
|
|
76
|
+
}
|
|
77
|
+
/** What EDGAR did, and which of the eleven things it is. A run whose pull request people decided on says that decision, with who approved and the merge commit, and no words of the proposal, which was written before the pull request. A run whose newest proposal decides to wait is not finished: its note says what it waits on. A run that opened a pull request and then failed says both. "I opened" counts only the pull requests that the run opened; one that it only worked on or found is linked after what it did. A run with no card names its workflow, because nothing else says what it was. A step that the engine stopped trying after too many uncharged tries says why in plain words, what to check, and the replay command. A pull request whose `url` is not an `http` or `https` address is left out. The pull requests that it opened end with the review's merge risk and its reason when the risk is one word above `low`: a line that every note carries is a line that nobody reads. */
|
|
78
|
+
function didOf(run, { outcome, end }, style) {
|
|
79
|
+
const word = outcome.outcome;
|
|
80
|
+
if (outcome.kind === "cancelled")
|
|
81
|
+
return { what: "stopped", lines: ["A person stopped the run before the end."] };
|
|
82
|
+
const workflow = end?.card_url === undefined && end?.workflow !== undefined
|
|
83
|
+
? `The ${style.text(end.workflow)} workflow`
|
|
84
|
+
: undefined;
|
|
85
|
+
const before = end?.failed_before ?? 0;
|
|
86
|
+
if (word === "done" && workflow !== undefined && before > 0)
|
|
87
|
+
return {
|
|
88
|
+
what: "recovered",
|
|
89
|
+
lines: [
|
|
90
|
+
`${workflow} works again, after ${String(before)} failed ${before === 1 ? "run" : "runs"}.`,
|
|
91
|
+
],
|
|
92
|
+
};
|
|
93
|
+
const all = pullsOf(end);
|
|
94
|
+
const bullet = ({ url, label }) => `• ${style.link(url, label)}`;
|
|
95
|
+
const pulls = all.map(bullet);
|
|
96
|
+
const mine = all.filter((pull) => pull.referenced !== true).map(bullet);
|
|
97
|
+
const head = mine.length === 1 ? "a pull request" : `${String(mine.length)} pull requests`;
|
|
98
|
+
const risky = riskOf(end, style);
|
|
99
|
+
const opened = mine.length === 0 ? [] : [`I opened ${head}:`, ...mine, ...risky];
|
|
100
|
+
const others = all.filter((pull) => pull.referenced === true).map(bullet);
|
|
101
|
+
const seen = others.length === 0
|
|
102
|
+
? []
|
|
103
|
+
: [
|
|
104
|
+
others.length === 1
|
|
105
|
+
? "See the pull request:"
|
|
106
|
+
: `See the ${String(others.length)} pull requests:`,
|
|
107
|
+
...others,
|
|
108
|
+
];
|
|
109
|
+
if (word !== "done") {
|
|
110
|
+
const why = end?.failure ?? outcome.message;
|
|
111
|
+
const stage = end?.failure === undefined ? undefined : end.failed_stage;
|
|
112
|
+
const who = workflow ?? "I";
|
|
113
|
+
const limit = why === undefined ? undefined : plainLimit(why);
|
|
114
|
+
const step = stage === undefined ? "" : ` the ${stage} stage`;
|
|
115
|
+
const failed = limit !== undefined
|
|
116
|
+
? `${who} could not finish${step}. ${style.text(`${limit.why} ${limit.next}, then run \`edgar run replay ${run}\`.`)}`
|
|
117
|
+
: stage === undefined
|
|
118
|
+
? sentence(`${who} could not finish:`, why, style)
|
|
119
|
+
: `${who} could not finish. ${sentence(`The ${stage} stage failed:`, why, style)}`;
|
|
120
|
+
return { what: "failed", lines: [...opened, failed, ...seen] };
|
|
121
|
+
}
|
|
122
|
+
const review = reviewOf(end);
|
|
123
|
+
if (review !== undefined) {
|
|
124
|
+
const by = end?.reviewed?.approved_by ?? [];
|
|
125
|
+
const commit = mergeOf(end);
|
|
126
|
+
return {
|
|
127
|
+
what: review,
|
|
128
|
+
lines: [
|
|
129
|
+
`${REVIEWED[review]}${pulls.length === 0 ? "." : ":"}`,
|
|
130
|
+
...pulls,
|
|
131
|
+
...(by.length === 0 ? [] : [`Approved by ${style.text(namesOf(by))}.`]),
|
|
132
|
+
...(commit === undefined ? [] : [`Merge commit ${style.text(commit)}.`]),
|
|
133
|
+
],
|
|
134
|
+
};
|
|
135
|
+
}
|
|
136
|
+
if (opened.length > 0)
|
|
137
|
+
return { what: "opened", lines: [...opened, ...seen] };
|
|
138
|
+
const summary = end?.summary?.trim() === "" ? undefined : end?.summary;
|
|
139
|
+
if ((end?.decision === "escalate" || end?.decision === "handoff") && summary !== undefined)
|
|
140
|
+
return {
|
|
141
|
+
what: "decision",
|
|
142
|
+
lines: [
|
|
143
|
+
`I need your decision. ${whole(summary, style)}`,
|
|
144
|
+
...(end.options ?? []).map((option, at) => `${at + 1}. ${whole(option, style)}`),
|
|
145
|
+
...seen,
|
|
146
|
+
style.reply ?? "Reply on the card to tell me what to do.",
|
|
147
|
+
],
|
|
148
|
+
};
|
|
149
|
+
const question = asked(end);
|
|
150
|
+
if (question !== undefined)
|
|
151
|
+
return {
|
|
152
|
+
what: "decision",
|
|
153
|
+
lines: [
|
|
154
|
+
`I need your call. ${whole(question, style)}`,
|
|
155
|
+
...seen,
|
|
156
|
+
style.reply ?? "Reply on the card to tell me what to do.",
|
|
157
|
+
],
|
|
158
|
+
};
|
|
159
|
+
if (end?.decision === "wait")
|
|
160
|
+
return {
|
|
161
|
+
what: "waits",
|
|
162
|
+
lines: [
|
|
163
|
+
summary === undefined
|
|
164
|
+
? "I'm waiting before I go on."
|
|
165
|
+
: sentence("I'm waiting before I go on:", summary, style),
|
|
166
|
+
...seen,
|
|
167
|
+
],
|
|
168
|
+
};
|
|
169
|
+
return {
|
|
170
|
+
what: "done",
|
|
171
|
+
lines: [
|
|
172
|
+
summary === undefined ? "I finished." : `I finished. ${sentence("", summary, style)}`.trim(),
|
|
173
|
+
...seen,
|
|
174
|
+
],
|
|
175
|
+
};
|
|
176
|
+
}
|
|
177
|
+
/** The card that a `run_created` payload or an end record names, when it has a link. */
|
|
178
|
+
export function noteCard(run) {
|
|
179
|
+
const url = run?.card_url;
|
|
180
|
+
if (run === undefined || url === undefined)
|
|
181
|
+
return undefined;
|
|
182
|
+
return {
|
|
183
|
+
url,
|
|
184
|
+
title: run.title ?? url,
|
|
185
|
+
...(run.card === undefined ? {} : { id: run.card }),
|
|
186
|
+
...(run.service === undefined ? {} : { service: run.service }),
|
|
187
|
+
};
|
|
188
|
+
}
|
|
189
|
+
/** A card as a line: its id as the link, then its service and title, or its title as the link when the run names no id. */
|
|
190
|
+
export function cardLine(card, style) {
|
|
191
|
+
if (card.id === undefined)
|
|
192
|
+
return style.link(card.url, card.title);
|
|
193
|
+
const what = card.service === undefined ? card.title : `${card.service}: ${card.title}`;
|
|
194
|
+
return `${style.link(card.url, card.id)} · ${style.text(what)}`;
|
|
195
|
+
}
|
|
196
|
+
/** A length of time in the largest unit that fits: seconds, minutes, or hours and minutes. */
|
|
197
|
+
function timeOf(ms) {
|
|
198
|
+
const seconds = Math.max(0, Math.round(ms / 1000));
|
|
199
|
+
if (seconds < 60)
|
|
200
|
+
return `${String(seconds)} s`;
|
|
201
|
+
const minutes = Math.round(seconds / 60);
|
|
202
|
+
if (minutes < 60)
|
|
203
|
+
return `${String(minutes)} min`;
|
|
204
|
+
return `${String(Math.floor(minutes / 60))} h ${String(minutes % 60)} min`;
|
|
205
|
+
}
|
|
206
|
+
/** A token count as a person reads it: `870`, `170k`, `1.2M`. */
|
|
207
|
+
function tokensOf(count) {
|
|
208
|
+
if (count < 1000)
|
|
209
|
+
return String(count);
|
|
210
|
+
return count < 999_500
|
|
211
|
+
? `${String(Math.round(count / 1000))}k`
|
|
212
|
+
: `${(count / 1_000_000).toFixed(1)}M`;
|
|
213
|
+
}
|
|
214
|
+
/** The last line: the run's number, how long it took, its tokens and cost when the run reports them, and a link to its page when the console has an address people can open. */
|
|
215
|
+
function usedOf(facts, style) {
|
|
216
|
+
const used = [
|
|
217
|
+
`Run ${facts.run}`,
|
|
218
|
+
...(facts.took === undefined ? [] : [facts.took]),
|
|
219
|
+
...(facts.tokens === undefined ? [] : [`${facts.tokens} tokens`]),
|
|
220
|
+
...(facts.cost === undefined ? [] : [facts.cost]),
|
|
221
|
+
].join(", ");
|
|
222
|
+
return facts.page === undefined ? used : `${used} · ${style.link(facts.page, "See each step")}`;
|
|
223
|
+
}
|
|
224
|
+
/** The plain values of the note: see `NoteFacts`. The pull requests are those the note names, so a run that a person stopped and a schedule that works again name none. */
|
|
225
|
+
function factsOf(event, { outcome, end, totals }, what, consoleUrl) {
|
|
226
|
+
const failure = what === "failed" ? (end?.failure ?? outcome.message) : undefined;
|
|
227
|
+
const limit = failure === undefined ? undefined : plainLimit(failure);
|
|
228
|
+
const why = failure === undefined
|
|
229
|
+
? undefined
|
|
230
|
+
: (limit?.why ?? plainFailure(failure) ?? plainFailure(outcome.kind ?? ""));
|
|
231
|
+
const stage = end?.failure === undefined ? undefined : end.failed_stage;
|
|
232
|
+
const question = what === "decision" ? asked(end) : undefined;
|
|
233
|
+
const summary = (question ?? end?.summary)?.trim() ?? "";
|
|
234
|
+
const pulls = what === "stopped" || what === "recovered" ? [] : pullsOf(end);
|
|
235
|
+
const used = (totals?.input_tokens ?? 0) + (totals?.output_tokens ?? 0);
|
|
236
|
+
const commit = what === "merged" ? mergeOf(end) : undefined;
|
|
237
|
+
const by = what === "merged" || what === "approved" ? (end?.reviewed?.approved_by ?? []) : [];
|
|
238
|
+
const [risk] = pulls.every((pull) => pull.referenced === true) ? [] : riskOf(end, asIs);
|
|
239
|
+
return {
|
|
240
|
+
run: event.run,
|
|
241
|
+
...(end === undefined ? {} : { took: timeOf(event.at - end.started) }),
|
|
242
|
+
...(used === 0 ? {} : { tokens: tokensOf(used) }),
|
|
243
|
+
...(totals?.cost === undefined ? {} : { cost: `$${totals.cost.toFixed(2)}` }),
|
|
244
|
+
...(consoleUrl === undefined
|
|
245
|
+
? {}
|
|
246
|
+
: { page: `${consoleUrl.replace(/\/$/, "")}/runs/${encodeURIComponent(event.run)}` }),
|
|
247
|
+
...(end?.workflow === undefined ? {} : { workflow: end.workflow }),
|
|
248
|
+
pulls,
|
|
249
|
+
...(by.length === 0 ? {} : { approvedBy: by }),
|
|
250
|
+
...(commit === undefined ? {} : { commit }),
|
|
251
|
+
...(risk === undefined ? {} : { risk }),
|
|
252
|
+
...(summary === "" ? {} : { summary }),
|
|
253
|
+
options: (end?.options ?? []).map((option) => option.trim()).filter((option) => option !== ""),
|
|
254
|
+
...(what !== "failed" || stage === undefined ? {} : { stage }),
|
|
255
|
+
...(failure === undefined ? {} : { failure }),
|
|
256
|
+
...(why === undefined ? {} : { why }),
|
|
257
|
+
...(limit === undefined ? {} : { next: limit.next }),
|
|
258
|
+
failedBefore: end?.failed_before ?? 0,
|
|
259
|
+
};
|
|
260
|
+
}
|
|
261
|
+
/** The part of a `run_outcome` payload that reads: all of it, or its `outcome` alone when its `end` or `totals` does not read. */
|
|
262
|
+
function readOf(payload) {
|
|
263
|
+
const whole = runEnded.safeParse(payload);
|
|
264
|
+
if (whole.success)
|
|
265
|
+
return whole.data;
|
|
266
|
+
const alone = runEnded.pick({ outcome: true }).safeParse(payload);
|
|
267
|
+
return alone.success ? { outcome: alone.data.outcome } : undefined;
|
|
268
|
+
}
|
|
269
|
+
/** The end note of a `run_outcome` event in a medium's `style`: who the card is assigned to, the card, what EDGAR did, and what the run used, with a link to the run's page when `consoleUrl` is given. A payload whose `end` or `totals` does not read gives the note of its `outcome` alone, so the note still says whether the run finished. `undefined` for any other event, and for a payload whose `outcome` does not read. */
|
|
270
|
+
export function endNote(event, style, consoleUrl) {
|
|
271
|
+
const read = event.kind === "run_outcome" ? readOf(event.payload) : undefined;
|
|
272
|
+
if (read === undefined)
|
|
273
|
+
return undefined;
|
|
274
|
+
const { end } = read;
|
|
275
|
+
const card = noteCard(end);
|
|
276
|
+
const did = didOf(event.run, read, style);
|
|
277
|
+
const facts = factsOf(event, read, did.what, consoleUrl);
|
|
278
|
+
return {
|
|
279
|
+
what: did.what,
|
|
280
|
+
repeat: did.what === "failed" && end?.repeat === true,
|
|
281
|
+
outcome: read.outcome.outcome,
|
|
282
|
+
card,
|
|
283
|
+
...(end?.assignee === undefined ? {} : { assignee: end.assignee }),
|
|
284
|
+
lines: [
|
|
285
|
+
...(end?.assignee === undefined ? [] : [`For ${style.text(end.assignee)}:`]),
|
|
286
|
+
...(card === undefined ? [] : [cardLine(card, style)]),
|
|
287
|
+
...did.lines,
|
|
288
|
+
usedOf(facts, style),
|
|
289
|
+
],
|
|
290
|
+
facts,
|
|
291
|
+
};
|
|
292
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import type { FailureKind } from "@kana-ai/edgar-contracts/provider";
|
|
2
|
+
import type { PortError } from "#define/context";
|
|
3
|
+
import { type LimitScheme } from "#outcome/limits";
|
|
4
|
+
import { type Failure } from "#outcome/outcome";
|
|
5
|
+
/** The failure of a `fetch` that threw: `cancelled`, `refused` for a host outside the call's capabilities, or `provider_unavailable`. */
|
|
6
|
+
export declare function fetchFailure(error: unknown, signal: AbortSignal, context: string): Failure;
|
|
7
|
+
/** Where a vendor's answer came from: the header family it reports its limits in, and the host. */
|
|
8
|
+
export interface LimitFrom {
|
|
9
|
+
readonly scheme: LimitScheme;
|
|
10
|
+
readonly source: string;
|
|
11
|
+
}
|
|
12
|
+
/** The failure of a vendor answer of `kind`, with the limit its headers report. A rate limit waits until the limit resets (`Retry-After` first, then the scheme's reset header), else one minute, and its limit is used up until then. */
|
|
13
|
+
export declare function vendorFailure(kind: FailureKind, context: string, cause: string, headers: Headers, from: LimitFrom, now?: number): Failure;
|
|
14
|
+
/** A port call that the engine refused or could not answer, as the failure of the tool that made it. */
|
|
15
|
+
export declare function portFailure(error: PortError): Failure;
|