@chipschat/hermes 1.0.13 → 1.0.15

package/README.md

@@ -202,8 +202,8 @@ npm test
 They run the bridge against Chips's conformance fake and a scripted Hermes API server
 (`test/fake-hermes.ts`), on Hermes's own routes and event names, and its webhook's signed
 readings. That includes Chips's golden scenario. Hermes's own files are in temporary homes: no
-test reads or writes `~/.hermes`. The SDK and the kit are in `vendor/`, packed from a Chips checkout with
-`pnpm release:sdk <this repo>/vendor`.
+test reads or writes `~/.hermes`. The SDK and the kit come from npm, at the version `package.json`
+pins.
 
 ```
 npm run e2e

package/dist/THIRD-PARTY-NOTICES.md

@@ -1,9 +1,9 @@
 # Third-party notices
 
-`dist/main.js` in @chipschat/hermes 1.0.13 carries these packages, bundled in. Each one's
+`dist/main.js` in @chipschat/hermes 1.0.15 carries these packages, bundled in. Each one's
 licence follows.
 
-## @chipschat/harness 0.0.0 (Apache-2.0)
+## @chipschat/harness 1.0.1 (Apache-2.0)
 
 Apache License
                            Version 2.0, January 2004
@@ -207,7 +207,7 @@ Apache License
    See the License for the specific language governing permissions and
    limitations under the License.
 
-## @chipschat/protocol 0.0.0 (Apache-2.0)
+## @chipschat/protocol 1.0.1 (Apache-2.0)
 
 Apache License
                            Version 2.0, January 2004

package/dist/main.js

@@ -20356,7 +20356,14 @@ var HARNESS_CAPABILITIES = {
    * and `context_window.change`, does them in its own way, and answers with its copy. What makes
    * an agent's Context window group worth drawing.
    */
-  contextWindows: "context_windows"
+  contextWindows: "context_windows",
+  /**
+   * The harness sends Chips a copy of the jobs it runs on its own, outside any space, and posts
+   * each run with what it cost, and takes a person's switch (ADR 0252): a socket of it says `jobs`
+   * in its `hello`, hears `job.change`, switches the job in its own way, and answers with its
+   * copy. What makes the harness page's "Its own jobs" group worth drawing.
+   */
+  jobs: "jobs"
 };
 var FORK_WAIT_MS = 6e4;
 
@@ -22533,6 +22540,115 @@ var AGENT_FIRST_NAMES = [
   "Zaid Zane Zeke Zeno Zev Ziggy"
 ].flatMap((line2) => line2.split(" "));
 
+// node_modules/@chipschat/protocol/dist/src/harness-jobs.js
+var HARNESS_JOBS_MAX = 24;
+var JOB_CHOICES_MAX = 12;
+var JOB_EVERY_MAX = 525600;
+var JOB_RUNS_POST_MAX = 200;
+var JOB_KINDS = ["heartbeat", "memory", "skills", "other"];
+var jobKind = external_exports.enum(JOB_KINDS);
+var JOB_RUN_OUTCOMES = ["done", "failed", "stopped"];
+var jobRunOutcome = external_exports.enum(JOB_RUN_OUTCOMES);
+var jobId = external_exports.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$/, "expected a job id").describe("The harness's own id for a job: stable, up to 80 letters, digits, `.`, `_`, `:` or `-`.");
+var minutes2 = external_exports.int().min(1).max(JOB_EVERY_MAX);
+var ascending3 = (choices) => choices.every((each, at) => at === 0 || each > (choices[at - 1] ?? 0));
+var jobFields = {
+  job_id: jobId,
+  name: external_exports.string().min(1).max(40).describe('What the harness calls it: "Dreaming".'),
+  about: external_exports.string().min(1).max(240).describe("What it does, in a sentence, for its page."),
+  kind: jobKind.describe("What it does, for its mark: `other` for anything else."),
+  every: minutes2.optional().describe("How often it runs, in minutes. Chips says it in words, with `next_at` for the time of day."),
+  when: external_exports.string().min(1).max(60).optional().describe("How often, in the harness's words, for a schedule that is not an interval."),
+  next_at: isoTimestamp.optional().describe("When it runs next, while it is on."),
+  for_agents: external_exports.array(id("agent")).max(200).optional().describe("The harness's agents it runs for, if it runs for some rather than the harness."),
+  on: external_exports.boolean().describe("Whether it runs now."),
+  editable: external_exports.boolean().describe("Whether a person may switch it from Chips."),
+  why_read_only: external_exports.string().min(1).max(120).optional().describe("Why not, in the harness's words, only when it is not `editable`."),
+  choices: external_exports.array(minutes2).min(1).max(JOB_CHOICES_MAX).refine(ascending3, { message: "The intervals go up, each named once." }).optional().describe("The intervals a person may pick, in minutes, shortest first, `every` among them.")
+};
+var harnessJob = external_exports.object(jobFields).refine((job) => job.every !== void 0 || job.when !== void 0, {
+  path: ["every"],
+  message: "Say how often it runs: `every` in minutes, or `when` in words."
+}).refine((job) => job.choices === void 0 || job.choices.includes(job.every ?? -1), {
+  path: ["choices"],
+  message: "`every` is one of `choices`."
+}).refine((job) => job.why_read_only === void 0 || !job.editable, {
+  path: ["why_read_only"],
+  message: "Say why only for a job that can't be switched."
+});
+var uniqueJobs = (jobs) => new Set(jobs.map((job) => job.job_id)).size === jobs.length;
+var harnessJobsPut = external_exports.object({
+  jobs: external_exports.array(harnessJob).max(HARNESS_JOBS_MAX).refine(uniqueJobs, { message: "Each job is named once." }).describe("Every job the harness runs on its own, whole: one left out is gone, runs and all."),
+  answers: id("change").optional().describe("The change this copy answers: made, and these are the jobs as they are now."),
+  refuses: external_exports.object({
+    change_id: id("change"),
+    message: external_exports.string().min(1).max(300).optional().describe("Why not, for the person.")
+  }).optional().describe("A change not made. The copy beside it is the jobs as they are now.")
+}).describe("`PUT /v1/harnesses/:id/jobs`: a harness's copy of the jobs it runs on its own.");
+var jobRun = external_exports.object({
+  job_id: jobId,
+  run_id: external_exports.string().min(1).max(160).describe("The harness's own id for the run."),
+  started_at: isoTimestamp,
+  ended_at: isoTimestamp,
+  outcome: jobRunOutcome.describe("`done`, `failed`, or `stopped` when something else ended it, such as a restart."),
+  quiet: external_exports.boolean().optional().describe("It did its work and had nothing to say: a heartbeat with nothing for anyone."),
+  waited: external_exports.boolean().optional().describe("It waited for an approval that nobody gave."),
+  error: external_exports.string().min(1).max(200).optional().describe("What went wrong, in the harness's words, for a run that failed or was stopped."),
+  agent_id: id("agent").optional().describe("The agent it ran for, when it runs for some."),
+  cost_usd: external_exports.number().min(0).max(1e4).optional().describe("What it cost, as the harness priced it: absent when the harness doesn't know."),
+  tokens: external_exports.int().min(0).optional().describe("Its tokens, in and out."),
+  model: external_exports.string().min(1).max(80).optional().describe("The model it ran on, in its words.")
+}).refine((run2) => Date.parse(run2.ended_at) >= Date.parse(run2.started_at), {
+  path: ["ended_at"],
+  message: "A run ends after it starts."
+}).describe("One run of a job, once it ended.");
+var jobRunsPost = external_exports.object({ runs: external_exports.array(jobRun).min(1).max(JOB_RUNS_POST_MAX) }).describe("`POST /v1/harnesses/:id/jobs/runs`: runs the harness finished. A run posted again says what it says over what was posted before, and what it leaves out stays: so a run may be posted once more with its cost, and never loses one.");
+var jobChangeAsk = external_exports.object({
+  on: external_exports.boolean(),
+  every: minutes2.optional().describe("One of the job's choices; its own when left out.")
+}).describe("`POST /v1/harnesses/:id/jobs/:job/changes`: on or off, and how often.");
+var JOB_CHANGE_STATES = ["waiting", "saved", "failed", "missed"];
+var jobChangeState = external_exports.enum(JOB_CHANGE_STATES);
+var jobChangeView = external_exports.object({
+  change_id: id("change"),
+  state: jobChangeState.describe("`missed` once `JOB_CHANGE_WAIT_MS` has passed with no answer; read, never stored."),
+  on: external_exports.boolean(),
+  every: minutes2.optional(),
+  asked_at: isoTimestamp,
+  answered_at: isoTimestamp.optional(),
+  message: external_exports.string().max(300).optional().describe("The harness's words, for a refusal.")
+}).describe("The last change a person asked of a job, and what became of it (ADR 0252).");
+var harnessJobView = external_exports.object({
+  ...jobFields,
+  week_usd: external_exports.number().min(0).optional().describe("What its runs of the last seven days cost: absent when none of them had a cost."),
+  week_runs: external_exports.int().min(0).describe("How many runs it made in the last seven days."),
+  runs_total: external_exports.int().min(0).describe("How many of its runs Chips holds."),
+  last_run: jobRun.optional(),
+  change: jobChangeView.optional()
+}).describe("One job as a person reads it: the harness's copy, what Chips counted, its change.");
+var harnessJobsView = external_exports.object({
+  harness_id: id("harness"),
+  jobs: external_exports.array(harnessJobView),
+  read_at: isoTimestamp.describe("When the harness last sent its copy."),
+  away: external_exports.boolean().describe("No socket of the harness hears changes now: read, not switched.")
+}).describe("`GET /v1/harnesses/:id/jobs`, for the harness's owner or an admin.");
+var jobRunsView = external_exports.object({
+  harness_id: id("harness"),
+  job_id: jobId,
+  runs: external_exports.array(jobRun).describe("Newest first."),
+  more: external_exports.boolean().describe("Whether older runs are left, for `before` the last one's start.")
+}).describe("`GET /v1/harnesses/:id/jobs/:job/runs?since=&before=&limit=`.");
+var jobChangeFrame = external_exports.object({
+  frame: external_exports.literal("job.change"),
+  change_id: id("change"),
+  harness_id: id("harness"),
+  job_id: jobId,
+  on: external_exports.boolean(),
+  every: minutes2.optional().describe("For a job with choices: one of them, the copy's own when the person named none."),
+  asked_by: id("person"),
+  asked_at: isoTimestamp
+}).describe("A person switched one of a harness's own jobs, or changed how often it runs (ADR 0252). Sent to a harness's socket that said `jobs` in its `hello`, now or never: it is not in the log. The harness answers with its copy of all its jobs, `answers` or `refuses` naming `change_id`.");
+
 // node_modules/@chipschat/protocol/dist/src/frames.js
 var clientHelloFrame = external_exports.object({
   frame: external_exports.literal("hello"),
@@ -22549,7 +22665,7 @@ var clientHelloFrame = external_exports.object({
     autonomy: autonomyLevel.optional().describe("The level the harness believes it has.")
   })).max(64).optional().describe("Not read by Chips: a connection is its token's, and the server's `hello` names the token's harness and its agents (ADR 0087). Absent for a person's client."),
   since: external_exports.int().nonnegative().optional().describe("Not read by Chips: a stream resumes from `subscribe`'s `since`."),
-  accepts: external_exports.array(external_exports.string().min(1).max(40)).max(32).optional().describe("Server frames beyond the base set this client understands, by the names in `SERVER_EXTENSIONS`. A name the server does not know is ignored rather than refused, so a client may name a frame a newer server sends and still be answered by an older one (ADR 0211, Phase 3). A client that says `events` is sent its replay in pages rather than one frame per event; one that says `presence` is sent an agent's state as it changes (ADR 0083); a harness's socket that says `restart` is sent `restart` when a person asks it to restart (ADR 0094); an owner's or admin's that says `join` is sent each join request as it changes (ADR 0122); a harness's that says `context` is sent `context.edit` when a person changes one of its context files (ADR 0134); a harness's that says `models` is sent `model.change` when a person changes an agent's model or effort (ADR 0140); a harness's that says `heartbeats` is sent `heartbeat.change` when a person switches an agent's heartbeat or changes how often it beats (ADR 0143); a harness's that says `context_windows` is sent `context_window.compact` and `context_window.change` when a person asks an agent to compact now or changes the limit it compacts itself at (ADR 0146); a person's that says `folders` is sent `folder.open` when they ask, from another of their devices, for a room's folder to be opened in Finder (ADR 0225), and `folder.run` when they ask for its project to be run or stopped there (ADR 0226); a person's that says `folder_runs` is sent `folder.run_state` when their Mac says how a run of theirs stands (ADR 0226); one that says nothing is sent what it was always sent, since an unknown frame is dropped in silence."),
+  accepts: external_exports.array(external_exports.string().min(1).max(40)).max(32).optional().describe("Server frames beyond the base set this client understands, by the names in `SERVER_EXTENSIONS`. A name the server does not know is ignored rather than refused, so a client may name a frame a newer server sends and still be answered by an older one (ADR 0211, Phase 3). A client that says `events` is sent its replay in pages rather than one frame per event; one that says `presence` is sent an agent's state as it changes (ADR 0083); a harness's socket that says `restart` is sent `restart` when a person asks it to restart (ADR 0094); an owner's or admin's that says `join` is sent each join request as it changes (ADR 0122); a harness's that says `context` is sent `context.edit` when a person changes one of its context files (ADR 0134); a harness's that says `models` is sent `model.change` when a person changes an agent's model or effort (ADR 0140); a harness's that says `heartbeats` is sent `heartbeat.change` when a person switches an agent's heartbeat or changes how often it beats (ADR 0143); a harness's that says `context_windows` is sent `context_window.compact` and `context_window.change` when a person asks an agent to compact now or changes the limit it compacts itself at (ADR 0146); a harness's that says `jobs` is sent `job.change` when a person switches one of the jobs it runs on its own (ADR 0252); a person's that says `folders` is sent `folder.open` when they ask, from another of their devices, for a room's folder to be opened in Finder (ADR 0225), and `folder.run` when they ask for its project to be run or stopped there (ADR 0226); a person's that says `folder_runs` is sent `folder.run_state` when their Mac says how a run of theirs stands (ADR 0226); one that says nothing is sent what it was always sent, since an unknown frame is dropped in silence."),
   context: contextBudget.optional().describe("How much of a room a harness is handed with each message for it (ADR 0088): 40 lines and 16,000 characters when absent, 200 and 32,000 at most. For this connection. A person's client is handed none.")
 }).describe("The first frame a client sends.");
 var subscribeFrame = external_exports.object({
@@ -22680,6 +22796,7 @@ var serverFrame = external_exports.discriminatedUnion("frame", [
   heartbeatChangeFrame,
   windowCompactFrame,
   windowChangeFrame,
+  jobChangeFrame,
   pingFrame,
   pongFrame,
   errorFrame
@@ -23864,7 +23981,8 @@ function acceptsFor(handlers) {
     ...handlers.context === void 0 ? [] : ["context"],
     ...handlers.models === void 0 ? [] : ["models"],
     ...handlers.heartbeats === void 0 ? [] : ["heartbeats"],
-    ...handlers.contextWindows === void 0 ? [] : ["context_windows"]
+    ...handlers.contextWindows === void 0 ? [] : ["context_windows"],
+    ...handlers.jobs === void 0 ? [] : ["jobs"]
   ];
 }
 var PATHS = {
@@ -23872,28 +23990,32 @@ var PATHS = {
   "harness-context": (id2) => `/v1/harnesses/${encodeURIComponent(id2)}/context`,
   model: (id2) => `/v1/agents/${encodeURIComponent(id2)}/model`,
   heartbeat: (id2) => `/v1/agents/${encodeURIComponent(id2)}/heartbeat`,
-  "context-window": (id2) => `/v1/agents/${encodeURIComponent(id2)}/context-window`
+  "context-window": (id2) => `/v1/agents/${encodeURIComponent(id2)}/context-window`,
+  jobs: (id2) => `/v1/harnesses/${encodeURIComponent(id2)}/jobs`
 };
 var FRAMES = {
   "context.edit": contextEditFrame,
   "model.change": modelChangeFrame,
   "heartbeat.change": heartbeatChangeFrame,
   "context_window.compact": windowCompactFrame,
-  "context_window.change": windowChangeFrame
+  "context_window.change": windowChangeFrame,
+  "job.change": jobChangeFrame
 };
 var Settings = class {
   put;
   harnessId;
   handlers;
+  post;
   /** The copy last given for each `kind:id`, for a refusal to carry. */
   sent = /* @__PURE__ */ new Map();
   /** The copy Chips last took for each `kind:id`, as JSON. */
   landed = /* @__PURE__ */ new Map();
   chains = /* @__PURE__ */ new Map();
-  constructor(put, harnessId, handlers) {
+  constructor(put, harnessId, handlers, post) {
     this.put = put;
     this.harnessId = harnessId;
     this.handlers = handlers;
+    this.post = post;
   }
   /** An agent's context files (`context_files`). */
   context(agentId2, copy) {
@@ -23915,6 +24037,24 @@ var Settings = class {
   contextWindow(agentId2, copy) {
     return this.send("context-window", agentId2, copy, {});
   }
+  /** The jobs the harness runs on its own, all of them (`jobs`). */
+  jobs(copy) {
+    return this.send("jobs", this.harnessId(), copy, {});
+  }
+  /**
+   * Runs of its jobs the harness finished (`jobs`), two hundred to a post. A run sent again says
+   * what it says over the one before, and what it leaves out stays, so send it once more when its
+   * cost is known, and again without one does no harm. Send the copy first:
+   * Chips refuses runs of a job its copy doesn't list.
+   */
+  async jobRuns(runs) {
+    if (this.post === void 0)
+      throw new Error("This connection can't post a job's runs.");
+    const path = `${PATHS.jobs(this.harnessId())}/runs`;
+    for (let at = 0; at < runs.length; at += JOB_RUNS_POST_MAX) {
+      await this.post(path, { runs: runs.slice(at, at + JOB_RUNS_POST_MAX) });
+    }
+  }
   /** An agent deleted: nothing is remembered of it, so a copy for an agent made again is sent. */
   forget(agentId2) {
     for (const kind of Object.keys(PATHS)) {
@@ -23962,6 +24102,8 @@ var Settings = class {
         return this.answer("model", frame.agent_id, frame.change_id, "change_id", () => handlers?.models?.(frame));
       case "heartbeat.change":
         return this.answer("heartbeat", frame.agent_id, frame.change_id, "change_id", () => handlers?.heartbeats?.(frame));
+      case "job.change":
+        return this.answer("jobs", this.harnessId(), frame.change_id, "change_id", () => handlers?.jobs?.(frame));
       case "context_window.compact":
         return this.answer("context-window", frame.agent_id, frame.change_id, "change_id", () => handlers?.contextWindows?.compact(frame));
       default:
@@ -24077,7 +24219,7 @@ var Chips = class _Chips {
       this.outbox.add(String(event["idempotency_key"]), event).catch(() => void 0);
     }
     this.orphans = [...kept?.runs ?? []];
-    this.settings = new Settings((path, body) => this.request("PUT", path, body), () => this.harnessId, options.settings);
+    this.settings = new Settings((path, body) => this.request("PUT", path, body), () => this.harnessId, options.settings, (path, body) => this.request("POST", path, body));
   }
   /**
    * The harness's copies of what a person changes from an agent's page (ADRs 0134, 0140, 0143,
@@ -27533,6 +27675,8 @@ var Bridge = class {
   toldModels = false;
   /** While Hermes's gateway restarts (Chips ADR 0094), the health watch says nothing: the restart says how it went. */
   held = false;
+  /** Restarts begun, so a health check asked before one, and answered after, is let go. */
+  holds = 0;
   /** What went wrong in the last restart, said in place of the watch's own words while Hermes doesn't answer. */
   why;
   /** Register the agents, start hearing what is said to them, and say how their gateways are. */
@@ -27573,6 +27717,7 @@ var Bridge = class {
   }
   /** Hold the health watch's words while Hermes's gateway restarts, and let them go after. */
   hold(held) {
+    if (held && !this.held) this.holds += 1;
     this.held = held;
   }
   /**
@@ -28037,11 +28182,18 @@ ${hook.lines}`);
       return note === void 0 ? {} : { note };
     }
   }
-  /** Trouble while a profile's gateway doesn't answer, and fine once all do (ADR 0083); nothing while a restart runs. */
+  /**
+   * Trouble while a profile's gateway doesn't answer, and fine once all do (ADR 0083); nothing while
+   * a restart runs, nor answers to a check asked before one began, even one over by now: they are of
+   * the gateways before, and a failed restart's words would go.
+   */
   async sayHowItIs() {
     if (this.held) return;
-    for (const agent of this.agents) agent.up = await agent.client.healthy();
-    if (this.held) return;
+    const holds2 = this.holds;
+    const answers2 = /* @__PURE__ */ new Map();
+    for (const agent of this.agents) answers2.set(agent, await agent.client.healthy());
+    if (this.holds !== holds2) return;
+    for (const [agent, up] of answers2) agent.up = up;
     const down = this.agents.filter((agent) => !agent.up);
     if (down.length === 0) this.why = void 0;
     const chips2 = this.options.chips;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chipschat/hermes",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "Hermes Agent as a Chips harness, on its Runs API: each profile a Chips agent, each room a Hermes session.",
   "license": "Apache-2.0",
   "repository": {
@@ -33,9 +33,9 @@
     "release": "npm run build && npm test && npm pack"
   },
   "devDependencies": {
-    "@chipschat/conformance": "file:vendor/chipschat-conformance-0.0.0.tgz",
-    "@chipschat/harness": "file:vendor/chipschat-harness-0.0.0.tgz",
-    "@chipschat/protocol": "file:vendor/chipschat-protocol-0.0.0.tgz",
+    "@chipschat/conformance": "1.0.1",
+    "@chipschat/harness": "1.0.1",
+    "@chipschat/protocol": "1.0.1",
     "@types/node": "22.19.0",
     "esbuild": "0.27.7",
     "tsx": "4.21.0",