runbios-sdk 0.2.1-rc.147 → 0.2.1-rc.153

package/dist/index.d.ts

@@ -36,7 +36,7 @@ import { Loop } from './resources/loop.js';
  * SDK version. Sent as part of the User-Agent header.
  * Must match package.json "version" -- enforced by a contract test.
  */
-export declare const VERSION = "0.2.1-rc.147";
+export declare const VERSION = "0.2.1-rc.153";
 export declare class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     readonly models: Models;

package/dist/index.js

@@ -36,7 +36,7 @@ import { Loop } from './resources/loop.js';
  * SDK version. Sent as part of the User-Agent header.
  * Must match package.json "version" -- enforced by a contract test.
  */
-export const VERSION = '0.2.1-rc.147';
+export const VERSION = '0.2.1-rc.153';
 export class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     models;

package/dist/resources/loop.d.ts

@@ -243,7 +243,22 @@ export declare class Loop {
         key: string;
         label: string;
     }>;
-    /** Every label in the workspace, with how many conversations carry it. */
+    /**
+     * Every label in the workspace, with how many conversations carry it and
+     * which master groups those conversations are in.
+     *
+     * TWO FIELDS ANSWER THE GROUP QUESTION, AND THEY ANSWER DIFFERENT ONES.
+     * `parent` is the group ALL of a label's conversations are in, and it is
+     * null the moment they disagree. `parents` is every group ANY of them are
+     * in, with how many of them are in each.
+     *
+     * Build a list of master groups out of `parents`. A label with 12
+     * conversations, 5 of them under `support`, reports `parent: null` and
+     * `parents: [{parent: 'support', traces: 5}]`, so code that reads only
+     * `parent` sees no group at all for it. The registry used to answer
+     * `parent: "support"` for all twelve, which named the group but put seven
+     * conversations in it that nobody had put there.
+     */
     listLabels(): Promise<LoopLabelCount[]>;
     /**
      * Build a training set from the feedback recorded so far.
@@ -453,11 +468,34 @@ export declare class Loop {
      * scoring something the rubric never asked for, is refused and reported in
      * `rejected` rather than silently dropped.
      *
-     * Pass `finish` to close a run you have decided to stop early. Without it an
-     * unfinished run stays open, which is the honest state for work that was
-     * abandoned rather than completed.
+     * Pass `finish` to close the run in the same call once you have nothing left
+     * to send. To close a run WITHOUT scores, call `stopRun`: an empty verdict
+     * list with `finish` does the same thing and reads like a mistake.
      */
     postVerdicts(runId: string, verdicts: LoopJudgeVerdict[], finish?: boolean): Promise<LoopJudgeVerdictResult>;
+    /**
+     * Close a run that has not finished.
+     *
+     * A judge may have one open run of its own at a time, so an open run BLOCKS
+     * the next one, and the runs that most need closing are the ones nobody can
+     * wait out: a run the agent has parked on an empty balance or a refused key
+     * stays open until the reason is fixed or somebody stops it.
+     *
+     * Nothing is deleted. Every verdict already recorded stays recorded, the
+     * counters keep saying how much of the selection was covered, and the
+     * conversations the run was holding are free for the next one. The run ends
+     * as `stopped` rather than `done`, so an interrupted pass and a completed
+     * one do not read alike.
+     *
+     * A run that finished on its own is not rewritten: stopping one answers 409.
+     *
+     * Returns the stopped run itself, like `startRun` and `getRun`, not the
+     * `{run}` envelope the service sends. Every other single-run method in this
+     * class unwraps, and `Loop.stop_run` in the Python SDK does too, so a
+     * caller who wrote `(await loop.stopRun(id)).status` against one of its
+     * siblings is right here as well.
+     */
+    stopRun(runId: string): Promise<LoopJudgeRun>;
     /**
      * Can an agent run here, is one running, and is it on for this workspace.
      * `available` is about the environment; `online` about the worker;
@@ -525,6 +563,15 @@ export declare class Loop {
      *
      * Send the `terms_version` it returns back in `createTrainingRule`. Read the
      * figures out of this response rather than inventing ceilings of your own.
+     *
+     * `valid: false` with an EMPTY `refusals` list is not nothing: check
+     * `unreachable`, which names every peer the platform could not reach. The
+     * rule is savable in that state and would be paused, but the estimate around
+     * it is not trustworthy -- both `worst_hourly_*` are `0`, and so are both
+     * `max_*_hours` beside them -- so do not quote those figures to anyone.
+     * `model_revision` is empty unless training-service actually pinned a
+     * commit; test `unreachable.length > 0` to tell a degraded pass from a
+     * refusal.
      */
     preflightTrainingRule(params: TrainingRulePreflightRequest): Promise<TrainingRulePreflight>;
     /**

package/dist/resources/loop.js

@@ -311,7 +311,22 @@ export class Loop {
         const q = key ? `?key=${encodeURIComponent(key)}` : '';
         return this._http.fetchDelete(`/api/loop/traces/${encodeURIComponent(traceId)}/labels/${encodeURIComponent(label)}${q}`);
     }
-    /** Every label in the workspace, with how many conversations carry it. */
+    /**
+     * Every label in the workspace, with how many conversations carry it and
+     * which master groups those conversations are in.
+     *
+     * TWO FIELDS ANSWER THE GROUP QUESTION, AND THEY ANSWER DIFFERENT ONES.
+     * `parent` is the group ALL of a label's conversations are in, and it is
+     * null the moment they disagree. `parents` is every group ANY of them are
+     * in, with how many of them are in each.
+     *
+     * Build a list of master groups out of `parents`. A label with 12
+     * conversations, 5 of them under `support`, reports `parent: null` and
+     * `parents: [{parent: 'support', traces: 5}]`, so code that reads only
+     * `parent` sees no group at all for it. The registry used to answer
+     * `parent: "support"` for all twelve, which named the group but put seven
+     * conversations in it that nobody had put there.
+     */
     async listLabels() {
         const res = await this._http.fetchGet('/api/loop/labels');
         return res.labels;
@@ -620,13 +635,39 @@ export class Loop {
      * scoring something the rubric never asked for, is refused and reported in
      * `rejected` rather than silently dropped.
      *
-     * Pass `finish` to close a run you have decided to stop early. Without it an
-     * unfinished run stays open, which is the honest state for work that was
-     * abandoned rather than completed.
+     * Pass `finish` to close the run in the same call once you have nothing left
+     * to send. To close a run WITHOUT scores, call `stopRun`: an empty verdict
+     * list with `finish` does the same thing and reads like a mistake.
      */
     async postVerdicts(runId, verdicts, finish = false) {
         return this._http.fetchPost(`/api/loop/runs/${encodeURIComponent(runId)}/verdicts`, { verdicts, finish });
     }
+    /**
+     * Close a run that has not finished.
+     *
+     * A judge may have one open run of its own at a time, so an open run BLOCKS
+     * the next one, and the runs that most need closing are the ones nobody can
+     * wait out: a run the agent has parked on an empty balance or a refused key
+     * stays open until the reason is fixed or somebody stops it.
+     *
+     * Nothing is deleted. Every verdict already recorded stays recorded, the
+     * counters keep saying how much of the selection was covered, and the
+     * conversations the run was holding are free for the next one. The run ends
+     * as `stopped` rather than `done`, so an interrupted pass and a completed
+     * one do not read alike.
+     *
+     * A run that finished on its own is not rewritten: stopping one answers 409.
+     *
+     * Returns the stopped run itself, like `startRun` and `getRun`, not the
+     * `{run}` envelope the service sends. Every other single-run method in this
+     * class unwraps, and `Loop.stop_run` in the Python SDK does too, so a
+     * caller who wrote `(await loop.stopRun(id)).status` against one of its
+     * siblings is right here as well.
+     */
+    async stopRun(runId) {
+        const res = await this._http.fetchPost(`/api/loop/runs/${encodeURIComponent(runId)}/stop`, {});
+        return res.run;
+    }
     // ── the agent ─────────────────────────────────────────────────────────
     //
     // The worker that calls a model on the workspace's behalf: it applies
@@ -731,6 +772,15 @@ export class Loop {
      *
      * Send the `terms_version` it returns back in `createTrainingRule`. Read the
      * figures out of this response rather than inventing ceilings of your own.
+     *
+     * `valid: false` with an EMPTY `refusals` list is not nothing: check
+     * `unreachable`, which names every peer the platform could not reach. The
+     * rule is savable in that state and would be paused, but the estimate around
+     * it is not trustworthy -- both `worst_hourly_*` are `0`, and so are both
+     * `max_*_hours` beside them -- so do not quote those figures to anyone.
+     * `model_revision` is empty unless training-service actually pinned a
+     * commit; test `unreachable.length > 0` to tell a degraded pass from a
+     * refusal.
      */
     async preflightTrainingRule(params) {
         return this._http.fetchPost('/api/loop/training-rules/preflight', params);

package/dist/types.d.ts

@@ -2647,8 +2647,13 @@ export interface LoopJudgeRun {
      * it for a week and items were still waiting. Nothing is deleted and posting
      * verdicts to it still works and still closes it as done. It exists so that
      * `open` keeps meaning "somebody is working on this".
+     *
+     * `stopped` is a run somebody closed on purpose before it finished, with
+     * `stopRun`. Separate from `done` because a run that covered three of forty
+     * conversations did not finish its work: every score it recorded is kept
+     * either way, and reading one as the other overstates what was evaluated.
      */
-    status: 'open' | 'done' | 'abandoned';
+    status: 'open' | 'done' | 'abandoned' | 'stopped';
     instructions: string;
     dimensions: LoopJudgeDimension[];
     model: string | null;
@@ -2929,9 +2934,34 @@ export interface LoopLabel {
     /** The dimension this value belongs to. `tag` for a bare name. */
     key: string;
 }
+/** One master group, and how many of a label's conversations are in it. */
+export interface LoopLabelParentCount {
+    parent: string;
+    traces: number;
+}
 export interface LoopLabelCount {
     label: string;
+    /**
+     * The master group ALL of this label's conversations are in, and nothing
+     * else. Null when they disagree: the registry used to answer the
+     * alphabetically last parent over a mixed group, so `billing` was reported
+     * under `support` while seven of its twelve conversations were in no group
+     * at all. Render "(in x)" from this field only.
+     */
     parent: string | null;
+    /**
+     * Every master group ANY of them are in, sorted, with how many of this
+     * label's conversations are in each. Empty when there are none.
+     *
+     * Read this, not `parent`, to discover which master groups exist: a label
+     * whose conversations disagree still belongs partly to a real group, and
+     * `parent` is null for it, so a picker built from `parent` alone loses the
+     * group along with the false claim. The count is per group rather than the
+     * label's own total, because adding a label's whole count to its parent is
+     * the same mistake one level down. What is in no group at all is `traces`
+     * minus the sum of these.
+     */
+    parents: LoopLabelParentCount[];
     traces: number;
     key: string;
 }
@@ -3114,6 +3144,22 @@ export interface TrainingRulePreflight {
     eval_ceiling_cents: number;
     warnings: string[];
     refusals: TrainingRulePreflightRefusal[];
+    /**
+     * Every peer the platform could not reach on this pass, one entry each, in
+     * the same `{stage, code, message}` shape as a refusal.
+     *
+     * A warning, not a refusal: an unreachable peer judged nothing, so it never
+     * refuses a save. It is still why the rule cannot fire — both
+     * `worst_hourly_*` come back `0` — so `valid` is `false`. Key a "cannot
+     * save" state on this when `refusals` is empty; the same sentences are also
+     * in `warnings`, so render one or the other.
+     *
+     * Key it on THIS, not on `model_revision`. A degraded pass echoes back the
+     * `model_revision` the request carried rather than emptying it, so
+     * `if (!model_revision)` is false on exactly the passes it was meant to
+     * catch. Use `unreachable.length > 0`, or `/^[0-9a-f]{40}$/`.
+     */
+    unreachable: TrainingRulePreflightRefusal[];
     key_check: TrainingRuleKeyCheck;
     terms_text: string;
     terms_version: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runbios-sdk",
-  "version": "0.2.1-rc.147",
+  "version": "0.2.1-rc.153",
   "description": "Official TypeScript SDK for the Run BiOS training and deployment platform API",
   "type": "module",
   "main": "./dist/index.js",