@kana-ai/edgar-sdk 0.1.5 → 0.1.6

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 CHANGED
@@ -158,6 +158,7 @@ A tool that throws ends as `permanent_failure(tool_error)`, which the engine nev
158
158
  - A fault that comes back after its card closed: when `create_card` finds no open card with the fingerprint, a tracker looks for the newest closed one as a `ClosedHolder` (`id`, `url`, `cancelled`, `closed_at`). When `reopens(closed, at)` is true, which is only for a card done less than `REOPEN_DAYS` (30) days before, the tracker writes `reopenedDescription(description, at)`, which adds `backLine(at)` and counts the sighting, moves the card to `ready`, and answers that card. Otherwise it files a new card whose description ends with `earlierLine(closed)`. When `closed.note` is set, that line also quotes the decision a person left there: `lastNote(comments, closed_at, person)` picks the newest comment before the close that `person` says a person wrote, not EDGAR or a bot, and `earlierLine` quotes it cut to 280 characters. Triage reads the line as part of the new card's description. A person's newer comment on the new card still wins, since a comment starts `resume` with that comment's text. A cancelled card is never opened again, since a person decided not to work it. The note goes in the description, not in a comment, because a comment that the tracker writes by itself would read as a person's.
159
159
  - `defineHook({ on, secrets, capabilities, check })` runs before (`before_tool`) or after (`after_tool`) each tool call that `[hooks] order` names it for. `check` returns `pass()`, or `deny(code, reason)`, which ends the call `permanent_failure(denied_by_hook)` with the reason.
160
160
  - A tracker's `mentions` is optional: a tracker that has it answers the comments made after `since` on any card that mention EDGAR's account, each with its `card`, and the engine reads it once a sweep so a mention on a card that no run holds starts the `mention` workflow.
161
+ - `updated_since: true` in `defineTracker` says that `list_cards` takes `updated_since`, an RFC 3339 time, and then answers only the cards changed at or after it; the manifest's `tracker.updated_since` says it to the engine. Most sweeps then ask only for the changed cards, and a full listing, the only one that may leave out a card that left, runs at the first sweep and every 10 minutes. A tracker without it gets no `updated_since` and is listed in full at each sweep.
161
162
  - `defineEventHook({ events, secrets, capabilities, deliver })` gets the events of each run whose kind is in `events`, in order per run and at least once. `deliver(event, ctx)` answers `done({})` once it took the event. A failure has the engine hand the event again, up to five times, with a backoff from one second; only the later events of that run wait meanwhile, so the other runs go on. After the last try, or at once on a permanent failure, the event is set aside with an `alert`, and `edgar outbox hooks` lists it. Each delivery has its own operation id, the same on each try. Use it to tell people about a run in a chat or by mail.
162
163
  - `endNote(event, style, consoleUrl?)` writes the note at the end of a run from its `run_outcome` event. It answers `{ what, outcome, card, assignee, lines, facts }`; `outcome` is the run's outcome as the engine names it, such as `done` or `permanent_failure`. `lines` are, in order: who the card is assigned to, the card, what EDGAR did, and what the run used. `assignee` is the name of the person the card is assigned to, as the card has it, and is there only for an assigned card. When it is set, the first of `lines` is the line that names that person, so a medium that can mention a person writes its own first line. `what` is the one thing a person must know: `opened` (a pull request), `merged`, `approved`, `changes` or `closed` (what people decided on the pull request, from the `reviewed` record of the `end` of a run with a card; a run with no card, such as a schedule that reads each pull request, never says a decision; `facts` then has `approvedBy`, the logins that approved, and `commit`, the first 7 characters of the merge commit of a merged pull request, and the lines carry no summary of the proposal), `decision`, `handed` (a stage handed the card back to a person, from `handed_to` of the `end` record; its line says "I handed the card to <person>." with the question the run left, else its summary, and `facts` has `handedTo`), `waits` (the run decided to wait, so it did not finish, and its line says what it waits on), `failed`, `stopped` (its line names who stopped the run when the engine recorded a person, and `facts` has `stoppedBy`), `done` or `recovered`. `facts` holds the same note as plain values that no style changed, for a medium that lays the note out by itself, as `@kana-ai/edgar-ext-slack` does: the run, how long it took, its tokens (left out for a run with no model token) and cost, the address of the run's page, the workflow, each pull request as `{ url, label }`, with `referenced: true` for one that the run did not open but worked on or found, the risk sentence, the summary and the options of the proposal, and for a failed run its stage, its message as the engine wrote it, and `why`, that message in plain words when its failure word is a known one. `notePull(url, number, referenced?)` gives the `{ url, label }` of one pull request, with the label `<repository>#<number>` and `referenced: true` when you pass it, or `undefined` for an address that is not `http` or `https`. "I opened" names only the pull requests that the run opened; the note links each other one after what the run did, as "See the pull request:". After the pull requests, the note says "The merge risk is <risk>: <the first sentence of risk_reason>." when the `end` record has a `risk` that is one word other than `low`. `style` says how your medium writes a link and makes a text safe: `{ link: (url, label) => string, text: (text) => string }`. Pass `consoleUrl` only when people can open the console at that address. When the `end` or the `totals` of a payload does not read, the note is written from the `outcome` alone, so it still says whether the run finished. It answers `undefined` for any other event, and for a `run_outcome` payload whose `outcome` it cannot read, so say in your medium that the run is over. `cardLine(card, style)` writes the card line alone, and `noteCard(runCard.parse(payload))` reads the card of a `run_created` payload, so the first message about a run can name its card as the end note does.
163
164
  - `defineEnvironment({ prepare, start, health, stop })` declares a service's running stack, each step a tool. A service names it with `[services.<name>] environment = { provider = "<ext>__<name>" }`. The stack is up only for a `check` stage, and one stack of a service is up at a time: a `check` stage that waits for it gives back its slot and takes the stack in the order the stages asked. For each `check` stage, the engine calls `stop` first, because a crash, a timeout or a failed `stop` can leave a stack up. Then it calls `prepare`, `start` and `health`, runs the checks, and calls `stop` again, also after a failed step. Each step gets the input `{ service, slot, run }`, where `slot` is always 1 and `run` is the sandbox's run, so a fixed port or Compose project name is safe. A failed step before the checks fails the stage with the step's name; a failed last `stop` writes an `alert`, and the next stage's first `stop` tries again. Each step must therefore be idempotent. A step that grants `sandbox:read` or `sandbox:write` runs in the run's sandbox.
@@ -57,6 +57,7 @@ export function toManifest(extension, version) {
57
57
  methods: [...tracker.methods],
58
58
  secrets: [...tracker.secrets],
59
59
  capabilities: [...tracker.capabilities],
60
+ ...(tracker.updatedSince ? { updated_since: true } : {}),
60
61
  },
61
62
  environments: Object.entries(extension.environments ?? {}).map(([name, e]) => ({
62
63
  name,
@@ -40,6 +40,8 @@ export type TrackerPort = {
40
40
  export interface TrackerSpec<S extends string, T extends TrackerIO = TrackerTypes> {
41
41
  readonly secrets?: readonly S[];
42
42
  readonly capabilities?: readonly Capability[];
43
+ /** `list_cards` answers only the cards changed at or after `updated_since` when the engine sends it, so most sweeps cost a page or two. */
44
+ readonly updated_since?: boolean;
43
45
  list_cards(input: T["list_cards"][0], ctx: Ctx<S>): Promise<Outcome<T["list_cards"][1]>>;
44
46
  card(input: T["card"][0], ctx: Ctx<S>): Promise<Outcome<T["card"][1]>>;
45
47
  comments(input: T["comments"][0], ctx: Ctx<S>): Promise<Outcome<T["comments"][1]>>;
@@ -59,6 +61,8 @@ export interface Tracker {
59
61
  readonly [trackerBrand]: true;
60
62
  readonly secrets: readonly string[];
61
63
  readonly capabilities: readonly Capability[];
64
+ /** Whether `list_cards` takes `updated_since`. */
65
+ readonly updatedSince: boolean;
62
66
  /** The methods it answers, in the manifest's order. */
63
67
  readonly methods: typeof trackerMethods | typeof withMentions;
64
68
  call(method: TrackerMethod, input: unknown, ctx: Ctx<string>): Promise<Outcome>;
@@ -23,6 +23,7 @@ export function defineTracker(spec) {
23
23
  [trackerBrand]: true,
24
24
  secrets: spec.secrets ?? [],
25
25
  capabilities: spec.capabilities ?? [],
26
+ updatedSince: spec.updated_since ?? false,
26
27
  methods: spec.mentions === undefined ? trackerMethods : withMentions,
27
28
  async call(method, input, ctx) {
28
29
  const erased = spec;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kana-ai/edgar-sdk",
3
- "version": "0.1.5",
3
+ "version": "0.1.6",
4
4
  "description": "Define EDGAR extensions: tools, a tracker, environments and hooks, and build their manifest.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -29,7 +29,7 @@
29
29
  "./testing": "./dist/src/testing/index.js"
30
30
  },
31
31
  "dependencies": {
32
- "@kana-ai/edgar-contracts": "0.1.5",
32
+ "@kana-ai/edgar-contracts": "0.1.6",
33
33
  "smol-toml": "1.9.1",
34
34
  "undici": "7.30.2"
35
35
  },