ordo-pow 0.2.1 → 0.2.2

package/README.md

@@ -15,7 +15,7 @@ Requires Node.js 22 or newer. No dependencies.
 ## Usage
 
 ```sh
-npx ordo-pow@latest <token> [--api <url>] [--no-open]
+npx ordo-pow@latest <token> [--notes <file>] [--api <url>] [--no-open]
 ```
 
 To keep the token out of your shell history, pass it in the environment instead:
@@ -26,12 +26,13 @@ ORDO_POW_TOKEN='opw1.…' npx ordo-pow@latest
 
 | Option | |
 |---|---|
+| `--notes <file>` | A `.txt` or `.md` file of your observations. The interviewer records what it states (measurements, your verdict on each outcome) and asks only about the rest. Its text goes to the model like a typed answer; its hash becomes evidence. |
 | `--api <url>` | Talk to this Ordo API instead of the address in the token |
 | `--no-open` | Print the signing link but do not open a browser |
 | `-h`, `--help` | Help |
 | `-v`, `--version` | Version |
 
-During the interview, type your answers. `/show` prints what has been recorded so far, `/quit` stops without sending anything. Before anything is sent you see the full record and confirm with `y`.
+During the interview, type your answers. `/show` prints what has been recorded so far, `/notes <file>` reads an observations file as your answer, `/quit` stops without sending anything. Before anything is sent you see the full record and confirm with `y`.
 
 When the agent wants to show a file of yours to the model (a photo) or transcribe one (a voice note), it asks first, file by file: `? Show bench.jpg (2.1 MB) to the interviewer model …? [y/N]`. Anything but `y` keeps the file hash-only.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ordo-pow",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Record proof of work on an Ordo stage: a short terminal interview through the 0G Private Computer Router (TEE providers only), signed in the Ordo console.",
   "license": "MIT",
   "type": "module",

package/src/cli.js

@@ -14,7 +14,7 @@ import { createRouterClient, trustText } from "./router.js";
 import { isLoopback, isTruthy, normalizeBaseUrl, parseInvocation, TOKEN_ENV } from "./token.js";
 
 export function usage() {
-  return `Usage: npx ${PACKAGE_NAME}@latest <token> [--api <url>] [--no-open]
+  return `Usage: npx ${PACKAGE_NAME}@latest <token> [--notes <file>] [--api <url>] [--no-open]
        ${TOKEN_ENV}=<token> npx ${PACKAGE_NAME}@latest
 
 Record proof of work on an Ordo stage. Copy the command from the stage in the Ordo
@@ -25,6 +25,9 @@ hashed on this machine; Ordo gets only the hashes. A photo or voice note goes to
 0G model only if you say yes for that file.
 
 Options:
+  --notes <file>  A .txt or .md file of your observations: the interviewer records what it
+                  states (measurements, your verdict on each outcome) and asks only about the rest.
+                  Its text goes to the 0G model like your typed answers; its hash is your evidence.
   --api <url>     Use this Ordo API address instead of the one in the token
   --no-open       Do not open the signing link in a browser
   -h, --help      Show this help
@@ -37,7 +40,8 @@ Environment:
                            used anyway when the Ordo deployment has no Router)
   NO_COLOR=1               Plain output
 
-During the interview: /show prints what is recorded, /quit stops without sending.
+During the interview: /show prints what is recorded, /notes <file> answers from a file,
+/quit stops without sending.
 
 Exit codes: 0 signed, 1 failed or expired, 2 bad usage or token, 3 stopped by you, 130 interrupted.`;
 }
@@ -150,7 +154,7 @@ export async function main(options = {}) {
 
     printBanner(terminal, session, { mock: mock ? (forcedMock ? "forced" : "ordo") : false, model: router.model });
     phase = "interview";
-    const interview = await runInterview({ session, router, terminal, client, cwd });
+    const interview = await runInterview({ session, router, terminal, client, cwd, notes: invocation.notes });
     if (interview.outcome === "quit") {
       terminal.print("");
       terminal.print("Stopped. Nothing was submitted.");

package/src/interview.js

@@ -7,15 +7,18 @@
 /** @import { OrdoClient } from "./ordo-api.js" */
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { formatBytes } from "./evidence.js";
+import { readFile } from "node:fs/promises";
+import { EvidenceError, formatBytes, hashEvidence } from "./evidence.js";
 import { contentText, createMediaQueue, stripImages } from "./media.js";
 import { targetText } from "./outcome-tools.js";
-import { buildSystemPrompt, KICKOFF } from "./prompt.js";
+import { buildSystemPrompt, KICKOFF, notesMessage } from "./prompt.js";
 import { describeRouterError } from "./router.js";
 import { createRecord, measurables, runTool, settleVision, toolDefinitions, unsentVision } from "./tools.js";
 
 /** Tool rounds in a row without hearing from the contributor before we stop and ask them. */
 const MAX_TOOL_ROUNDS = 8;
+/** the largest observations file the interviewer reads */
+const MAX_NOTES_BYTES = 64 * 1024;
 
 /**
  * @typedef {object} InterviewResult
@@ -33,10 +36,11 @@ const MAX_TOOL_ROUNDS = 8;
  *   client?: Pick<OrdoClient, "output" | "askMachine" | "getSession">,
  *   cwd?: string,
  *   maxEvidenceBytes?: number,
+ *   notes?: string | null,
  * }} options
  * @returns {Promise<InterviewResult>}
  */
-export async function runInterview({ session, router, terminal, client, cwd = process.cwd(), maxEvidenceBytes }) {
+export async function runInterview({ session, router, terminal, client, cwd = process.cwd(), maxEvidenceBytes, notes = null }) {
   const { style } = terminal;
   const stage = session.stage;
   const record = createRecord();
@@ -55,6 +59,36 @@ export async function runInterview({ session, router, terminal, client, cwd = pr
   ];
   let inputEnded = false;
   let quitRequested = false;
+
+  /**
+   * The contributor's observations file: hashed as evidence, and its text sent to the interviewer as their answers.
+   * @param {string} input
+   * @returns {Promise<string | null>} the message, or null when the file cannot be used (the reason is printed)
+   */
+  async function loadNotes(input) {
+    let file;
+    try {
+      file = await hashEvidence(input, { cwd, maxBytes: MAX_NOTES_BYTES });
+    } catch (err) {
+      if (err instanceof EvidenceError) {
+        terminal.error(`  Notes: ${err.message}`);
+        return null;
+      }
+      throw err;
+    }
+    const text = (await readFile(file.path, "utf8")).replace(/\r\n/g, "\n").trim();
+    if (!text) {
+      terminal.error(`  Notes: ${file.name} is empty.`);
+      return null;
+    }
+    if (/[\u0000-\u0008\u000e-\u001f]/.test(text.slice(0, 4096))) {
+      terminal.error(`  Notes: ${file.name} is not a text file. Use a .txt or .md file of your observations.`);
+      return null;
+    }
+    if (!record.evidence.some((e) => e.sha256 === file.sha256)) record.evidence.push({ name: file.name, sha256: file.sha256, size: file.size, mediaType: "text/plain" });
+    terminal.print(style.green(`  ✓ read your notes ${file.name} (${formatBytes(file.size)}), sha256 ${file.sha256.slice(0, 16)}…: its text goes to the interviewer as your answers, and its hash is your evidence`));
+    return notesMessage({ name: file.name, sha256: file.sha256, text });
+  }
   let warnedTee = false;
   let toolRounds = 0;
 
@@ -82,7 +116,17 @@ export async function runInterview({ session, router, terminal, client, cwd = pr
         continue;
       }
       if (command === "/help" || command === "/?") {
-        terminal.print(style.dim("  /show  what is recorded so far\n  /quit  stop without sending anything"));
+        terminal.print(style.dim("  /show          what is recorded so far\n  /notes <file>  answer from a text file of your observations\n  /quit          stop without sending anything"));
+        continue;
+      }
+      if (command === "/notes" || command.startsWith("/notes ")) {
+        const file = text.slice("/notes".length).trim();
+        if (!file) {
+          terminal.print(style.dim("  /notes <file>: a .txt or .md file of your observations, for example /notes ~/stage-01.txt"));
+          continue;
+        }
+        const message = await loadNotes(file);
+        if (message) return message;
         continue;
       }
       // Anything else, including absolute paths that start with "/", is an answer.
@@ -149,6 +193,15 @@ export async function runInterview({ session, router, terminal, client, cwd = pr
     }
   }
 
+  // an observations file given on the command line (--notes) is the contributor's first answer
+  if (notes) {
+    const message = await loadNotes(notes);
+    if (message) {
+      transcript.push({ role: "user", content: message, at: new Date().toISOString() });
+      messages.push({ role: "user", content: message });
+    }
+  }
+
   /** @param {string} line */
   const announce = (line) => terminal.print(style.green(`  ✓ ${line}`));
   /** @param {string} line */

package/src/outcome-tools.js

@@ -204,15 +204,22 @@ export async function reviewOutcome(args, ctx, announce) {
  * @param {Record<string, unknown>} args
  * @param {ToolContext} ctx
  * @param {(line: string) => void} announce
- * @returns {ToolOutcome}
+ * @returns {Promise<ToolOutcome>}
  */
-export function confirmOutcome(args, ctx, announce) {
+export async function confirmOutcome(args, ctx, announce) {
   const o = findOutcome(ctx.stage, args.key);
   if (!o) return fail(`Unknown outcome. Use one of: ${(ctx.stage.outcomes ?? []).map((x) => x.key).join(", ") || "(this stage has none)"}.`);
   const verdict = typeof args.verdict === "string" ? args.verdict.trim().toLowerCase() : "";
   if (!VERDICTS.includes(/** @type {any} */ (verdict))) return fail(`verdict is one of: ${VERDICTS.join(", ")}.`);
+  // a model that skips review_outcome would otherwise be refused again and again: show the outcome here (its file is
+  // saved and its path printed, so the contributor can open what they are confirming), then record the verdict
+  let autoReviewed = false;
+  if (o.captured && o.output && !ctx.record.reviewed[o.key]) {
+    const shown = await reviewOutcome({ key: o.key }, ctx, announce);
+    if (!shown.result.ok) return shown;
+    autoReviewed = true;
+  }
   const reviewed = ctx.record.reviewed[o.key];
-  if (o.captured && o.output && !reviewed) return fail(`Show ${o.label} to the contributor first: call review_outcome with key "${o.key}".`);
   if (verdict === "confirm" && !reviewed) return fail(`Nothing was captured for ${o.label}, so there is nothing to confirm. Record dispute or unsure, with what the contributor said.`);
   const raw = typeof args.observed === "string" && args.observed.trim() !== "" ? Number(args.observed) : args.observed;
   if (raw !== undefined && raw !== null && (typeof raw !== "number" || !Number.isFinite(raw))) return fail("observed must be a number: the value the contributor observed, or leave it out.");
@@ -227,7 +234,7 @@ export function confirmOutcome(args, ctx, announce) {
   else ctx.record.confirmations.push(c);
   const word = verdict === "confirm" ? "confirmed" : verdict === "dispute" ? "disputed" : "unsure";
   announce(`${o.label}: ${word}${c.observed !== undefined ? `, observed ${c.observed}${o.metric.unit ? ` ${o.metric.unit}` : ""}` : ""}${note ? ` (${note.length > 70 ? `${note.slice(0, 69)}…` : note})` : ""}`);
-  return ok({ recorded: c, replacedEarlierVerdict: index >= 0, outcomesToReview: pendingOutcomes(ctx.stage, ctx.record).map((x) => x.key) });
+  return ok({ recorded: c, replacedEarlierVerdict: index >= 0, ...(autoReviewed ? { reviewedNow: true } : {}), outcomesToReview: pendingOutcomes(ctx.stage, ctx.record).map((x) => x.key) });
 }
 
 /**

package/src/prompt.js

@@ -105,3 +105,19 @@ export function buildSystemPrompt(session) {
 
 /** The first user turn, so models that need one have it. Not part of the transcript. */
 export const KICKOFF = "The contributor has opened the terminal and is ready. Start the interview.";
+
+/**
+ * The contributor's observations file, sent as their answer. The model records what it states and asks only about the rest.
+ * @param {{ name: string, sha256: string, text: string }} notes
+ */
+export function notesMessage(notes) {
+  return `My observations for this stage are in the file ${notes.name} (sha256 ${notes.sha256.slice(0, 16)}…, attached as evidence). Use them as my answers:
+- record every measurement it gives with record_measurement;
+- review each outcome the machine captured and record my verdict from the file with confirm_outcome (confirm, or dispute with the value I observed);
+- add what else it says as notes.
+Do not ask me again for anything the file answers. Ask only about what it leaves out or contradicts, then give me your summary and call finish.
+
+--- ${notes.name} ---
+${notes.text}
+--- end of ${notes.name} ---`;
+}

package/src/token.js

@@ -99,6 +99,7 @@ export function isLoopback(url) {
  * @property {boolean} open
  * @property {ParsedToken | null} token
  * @property {"argument" | "env" | null} tokenSource
+ * @property {string | null} notes  An observations file to answer from (--notes)
  */
 
 /**
@@ -116,6 +117,7 @@ export function parseInvocation(argv, env) {
       strict: true,
       options: {
         api: { type: "string" },
+        notes: { type: "string" },
         "no-open": { type: "boolean" },
         help: { type: "boolean", short: "h" },
         version: { type: "boolean", short: "v" },
@@ -127,7 +129,7 @@ export function parseInvocation(argv, env) {
       throw new UsageError(`Unknown option. Run with --help to see the options.`);
     }
     if (code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE") {
-      throw new UsageError(`An option has a missing or unexpected value (--api needs a URL, for example --api https://ordo.example.com).`);
+      throw new UsageError(`An option has a missing or unexpected value (--api needs a URL, for example --api https://ordo.example.com; --notes needs a file).`);
     }
     throw new UsageError(`Could not read the arguments. Run with --help to see the options.`);
   }
@@ -135,7 +137,8 @@ export function parseInvocation(argv, env) {
   const help = Boolean(values.help);
   const version = Boolean(values.version);
   const open = !values["no-open"] && !isTruthy(env.ORDO_POW_NO_OPEN);
-  if (help || version) return { help, version, open, token: null, tokenSource: null };
+  const notes = typeof values.notes === "string" && values.notes.trim() ? values.notes : null;
+  if (help || version) return { help, version, open, token: null, tokenSource: null, notes };
 
   if (positionals.length > 1) {
     throw new UsageError(`Expected one token, got ${positionals.length} arguments.`);
@@ -156,7 +159,7 @@ export function parseInvocation(argv, env) {
   }
   const token = parseToken(raw);
   if (values.api !== undefined) token.apiBaseUrl = normalizeBaseUrl(values.api, "--api");
-  return { help, version, open, token, tokenSource };
+  return { help, version, open, token, tokenSource, notes };
 }
 
 /** @param {string | undefined} value */