@jr2/orchestrator 0.5.1 → 0.7.0

package/src/vocabulary.ts

@@ -101,6 +101,27 @@ export function inputSchemaOf(machine: AnyStateMachine): z.ZodObject | undefined
   return inputSchemas.get(machine.config);
 }
 
+/**
+ * The door of a wrapper under a parent (ADR-0033). No other door reads a parent's input, so the
+ * wrapper parses it, and the parsed shape is what it uses: defaults are applied and unknown keys
+ * go. A key in `beside` is no one's to send, so it stays out of the parse and rides beside the
+ * result. A value that is wrong is a defect of the parent's Machine: a throw, and its `onError`.
+ *
+ * @param refusal - the start of the error, which says what the refusal saved
+ * @internal
+ */
+export function parsedNestedDoor(
+  door: z.ZodObject,
+  value: Record<string, unknown>,
+  beside: readonly string[],
+  refusal: string,
+): Record<string, unknown> {
+  const kept = Object.entries(value).filter(([key, v]) => beside.includes(key) && v !== undefined);
+  const parsed = door.safeParse(Object.fromEntries(Object.entries(value).filter(([key]) => !beside.includes(key))));
+  if (!parsed.success) throw new Error(`${refusal}: ${parsed.error.message}`);
+  return { ...(parsed.data as Record<string, unknown>), ...Object.fromEntries(kept) };
+}
+
 /** A zod schema, by its shape: the Instance can resolve a zod of its own, so `instanceof` does not
  * tell. */
 export function isZodSchema(value: unknown): boolean {
@@ -187,10 +208,8 @@ export function loadWarningsOf(machine: AnyStateMachine): string[] {
  *
  * Only the root Machine of a run gets it. A Machine that another Machine invokes gets the input
  * that its parent gives it. A `workspace()` passes its input to its body, so the body of a root
- * `workspace()` gets it too: `Workspaced<HostInjectedInput & RunInput, "app">`.
- *
- * The `spec` of a root `workspace()` also gets it, and the type of its input shows it:
- * ``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``.
+ * `workspace()` gets it too: `Workspaced<HostInjectedInput & RunInput, "app">`. For example, a cut
+ * can name a branch for each run: `` branch: `fix/${context.instanceId}` ``.
  *
  * It is not the run id. Use it, for example, to give each run a branch of its own.
  *

package/src/wire.ts

@@ -152,6 +152,23 @@ export type PickAnswerNotice = {
 
 export type Notice = MemoryLimitNotice | ConversationNewNotice | PickAnswerNotice;
 
+// ---- Steering messages (ADR-0002, ADR-0062) ----------------------------------------------------
+// Free text to one Agent slot, with its author. Not a notice: a notice is a fact with no author,
+// and the model weighs a Steering message by who wrote it. The two ride one ledger and one
+// transport, and the Harness frames each message by its author.
+
+/** Who wrote a Steering message. `caller`: a Caller sent it from outside the run (ADR-0078), with
+ * the name jr2 shows and the party it says it acts for. `machine`: the Machine sent it with its
+ * `steer` action; `from` is the party whose words it relays, when it relays some. */
+export type SteeringAuthor =
+  | { kind: "caller"; via: "token" | "jwt" | "hook"; name: string; onBehalfOf?: string }
+  | { kind: "machine"; from?: { party: "agent" | "gate"; id: string } };
+
+/** One Steering message, as the admission and the surface read carry it. `scope: "slot"` is the
+ * address kind it uses in the ledger. `at`: when it was sent (ISO). The Harness writes the frame;
+ * `text` is the author's. */
+export type SteeringMessage = { kind: "steering"; scope: "slot"; text: string; author: SteeringAuthor; at: string };
+
 /** Response header: the offset to resume the stream from (every stream read carries it). */
 export const STREAM_NEXT_OFFSET_HEADER = "stream-next-offset";
 
@@ -267,18 +284,18 @@ export type EchoRequest = { events: EchoEvent[] };
 /** One Repo Slot to attach. The Orchestrator resolves the Repo's `identity` and cache `key`
  * (repo-identity.ts) — the Harness never re-derives them, so the cache it clones from and the node
  * cache the operator mounted agree by construction (ADR-0051). `url` is the Binding's own spelling,
- * the push url (ADR-0005); `ref` is the base the branch starts from, omitted for the Repo's default
- * branch. */
+ * the push url (ADR-0005); `ref` is the base that `default/` stays on and a new branch starts from,
+ * omitted for the Repo's default branch. */
 export type AttachSlot = { slot: string; url: string; identity: string; key: string; ref?: string };
 
-/** What `POST /attach` accepts: the slots in declaration order, the Workspace's branch, and — for a
- * reviewer's seat — the sha the detached review worktree is forced to (ADR-0028). */
-export type AttachRequest = { slots: AttachSlot[]; branch: string; reviewSha?: string };
+/** What `POST /attach` accepts: the slots in declaration order. The Workspace only clones, so the
+ * request names no branch and no commit (ADR-0075). */
+export type AttachRequest = { slots: AttachSlot[] };
 
-/** What `POST /attach` answers (200): the branch worktree per slot, and the review worktree per
- * slot when the request named a `reviewSha`. Freshness is the operator's verdict on the Sandbox,
- * which the Orchestrator reads itself — never the Harness's to report. */
-export type AttachResponse = { repos: Record<string, string>; review?: Record<string, string> };
+/** What `POST /attach` answers (200): the folder of each slot, and the base that each slot's
+ * `default/` holds. Freshness is the operator's verdict on the Sandbox, which the Orchestrator
+ * reads itself — never the Harness's to report. */
+export type AttachResponse = { repos: Record<string, string>; bases: Record<string, string> };
 
 /** What a failed attach answers: 400 for a body that is not an `AttachRequest`, 500 when a step
  * failed — `slot` names the Repo Slot, and `error` carries the step and git's own stderr. */
@@ -312,7 +329,7 @@ export type SyncAnswer =
 
 /** What `POST /exec/:id` accepts: argv (never shell text), an absolute `cwd` or none, the timeout,
  * and how many characters of the stream's end the output keeps. */
-export type ExecRequest = { argv: string[]; cwd?: string; timeoutMs: number; tail: number };
+export type ExecRequest = { argv: string[]; cwd?: string; root?: true; timeoutMs: number; tail: number };
 
 /** How an exec ended. Every one is output; none is a fault. */
 export type ExecOutcome =