@raibitsi/tiresias 1.0.1 → 1.1.0

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.
Files changed (50) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +49 -26
  3. package/dist/browsecli.js +4 -3
  4. package/dist/cdp.js +22 -1
  5. package/dist/cli.js +82 -29
  6. package/dist/config.js +16 -1
  7. package/dist/confirm.js +6 -2
  8. package/dist/cooldown.js +57 -32
  9. package/dist/dailylog.js +11 -5
  10. package/dist/engine.js +3 -3
  11. package/dist/envelope.js +1 -1
  12. package/dist/fetcher.js +5 -0
  13. package/dist/filereply.js +7 -1
  14. package/dist/formflow.js +21 -3
  15. package/dist/forms.js +257 -34
  16. package/dist/getactions.js +99 -0
  17. package/dist/history.js +8 -5
  18. package/dist/hook.js +2 -0
  19. package/dist/hosts.js +11 -11
  20. package/dist/keys.js +420 -18
  21. package/dist/mcp.js +10 -10
  22. package/dist/needs.js +9 -5
  23. package/dist/parentwatch.js +6 -16
  24. package/dist/pdf.js +4 -1
  25. package/dist/pdfchild.js +0 -2
  26. package/dist/pdfproc.js +26 -11
  27. package/dist/pdfwatch.js +14 -0
  28. package/dist/pipeline.js +11 -2
  29. package/dist/profiles.js +3 -3
  30. package/dist/queue.js +4 -2
  31. package/dist/receipts.js +2 -2
  32. package/dist/render.js +103 -24
  33. package/dist/resume.js +8 -6
  34. package/dist/rules.js +10 -3
  35. package/dist/safebrowsing.js +3 -3
  36. package/dist/safety.js +9 -3
  37. package/dist/sandbox.js +1 -1
  38. package/dist/saved.js +24 -9
  39. package/dist/savedlock.js +99 -5
  40. package/dist/settings.js +7 -3
  41. package/dist/shelf.js +1 -1
  42. package/dist/slips.js +43 -1
  43. package/dist/store.js +119 -25
  44. package/dist/tabs.js +1 -1
  45. package/dist/textview.js +10 -0
  46. package/dist/translate.js +22 -2
  47. package/dist/types.js +2 -2
  48. package/dist/watchflow.js +1 -2
  49. package/dist/work.js +4 -2
  50. package/package.json +1 -1
package/dist/savedlock.js CHANGED
@@ -1,26 +1,101 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
2
  // Saves run in killable MCP servers. Publish a nonempty lock directory atomically, so even a kill during
3
- // acquisition leaves a named owner. Only ESRCH permits recovery; a live owner is never timed out.
3
+ // acquisition leaves a named owner. Recovery needs proof the owner is gone: ESRCH, or (v1.1, Codex K.9) the pid now
4
+ // belongs to a different process than the one whose start stamp the lock recorded. A live owner is never timed out.
4
5
  // Recovery removes the dead owner's unique entry, then rmdir: a delayed recoverer cannot remove a new,
5
6
  // nonempty lock. Config commands keep ownedlock.ts's deliberately manual recovery policy.
7
+ import { execFileSync } from "node:child_process";
6
8
  import { randomBytes } from "node:crypto";
7
9
  import fs from "node:fs";
10
+ import os from "node:os";
8
11
  import path from "node:path";
9
12
  import { NOFOLLOW, NONBLOCK } from "./store.js";
10
13
  const TRY_MS = 1_000;
11
14
  const OWNER_RE = /^[1-9][0-9]*-[0-9a-f]{24}$/;
12
15
  const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
13
- function dead(pid) {
16
+ // A process's start stamp, as the kernel recorded it, or null. Format: "<scope>|<value>".
17
+ // - Linux: scope = boot id + pid namespace + time namespace (ours), value = start time in clock ticks since boot
18
+ // (/proc/<pid>/stat field 22).
19
+ // - Elsewhere: scope = "ps" + host name, value = ps's lstart, printed with TZ=UTC and LC_ALL=C so every reader
20
+ // prints it the same way (Codex r4: time zone and locale change the text).
21
+ // The value stays the same for the life of a process whatever the wall clock does, and differs for a later
22
+ // process given the same pid.
23
+ function scope() {
24
+ try {
25
+ if (process.platform === "linux") {
26
+ // Codex r5: stat's start time includes the READER's time-namespace offset, so the time namespace is part of
27
+ // the scope too. Kernels without time namespaces have no such link: one shared clock.
28
+ let timeNs = "no-time-ns";
29
+ try {
30
+ timeNs = fs.readlinkSync("/proc/self/ns/time");
31
+ }
32
+ catch {
33
+ // kept as one shared clock
34
+ }
35
+ return `linux:${fs.readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()}:${fs.readlinkSync("/proc/self/ns/pid")}:${timeNs}`;
36
+ }
37
+ return `ps:${os.hostname()}`;
38
+ }
39
+ catch {
40
+ return null;
41
+ }
42
+ }
43
+ function startStamp(pid) {
44
+ const sc = scope();
45
+ if (!sc)
46
+ return null;
47
+ try {
48
+ if (process.platform === "linux") {
49
+ // Only meaningful when this /proc numbers pids the way we do (Codex r6: a procfs mounted for another pid
50
+ // namespace can map our number to someone else) and that pid lives in OUR pid namespace.
51
+ if (fs.readlinkSync("/proc/self") !== String(process.pid))
52
+ return null;
53
+ if (fs.readlinkSync(`/proc/${pid}/ns/pid`) !== fs.readlinkSync("/proc/self/ns/pid"))
54
+ return null;
55
+ const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
56
+ const ticks = stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19];
57
+ return ticks && /^\d+$/.test(ticks) ? `${sc}|${ticks}` : null;
58
+ }
59
+ const env = { PATH: process.env.PATH ?? "/usr/bin:/bin", TZ: "UTC", LC_ALL: "C" };
60
+ const t = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", timeout: 2_000, env, stdio: ["ignore", "pipe", "ignore"] }).trim();
61
+ return t ? `${sc}|${t}` : null;
62
+ }
63
+ catch {
64
+ return null;
65
+ }
66
+ }
67
+ let ownStamp;
68
+ const myStamp = () => (ownStamp === undefined ? (ownStamp = startStamp(process.pid)) : ownStamp);
69
+ // The owner is gone if its pid no longer exists (ESRCH). Codex K.9: a pid can be reused, so when the pid is alive
70
+ // and the lock recorded its owner's start stamp, a different stamp on that pid now means a different process,
71
+ // but only when the lock was taken in the same scope (same machine and boot, same pid namespace) as ours; a lock
72
+ // from another container or host is never judged this way. The wall clock is never used (Codex r3). Anything
73
+ // unclear, including an old lock with no stamp or a stamp that cannot be read, counts as alive.
74
+ export function dead(pid, recordedStamp) {
14
75
  if (!Number.isSafeInteger(pid) || pid <= 0)
15
76
  return false;
16
77
  try {
17
78
  process.kill(pid, 0);
18
- return false;
19
79
  }
20
80
  catch (e) {
21
81
  return e.code === "ESRCH";
22
82
  }
83
+ if (!recordedStamp)
84
+ return false;
85
+ const sep = recordedStamp.lastIndexOf("|");
86
+ if (sep < 0)
87
+ return false;
88
+ const now = startStamp(pid);
89
+ if (now === null)
90
+ return false;
91
+ const nowSep = now.lastIndexOf("|");
92
+ // Both stamps must come from the same scope, checked on the stamp just read (Codex r6: a host name change
93
+ // between two samples must not turn a scope change into a "different process").
94
+ if (now.slice(0, nowSep) !== recordedStamp.slice(0, sep))
95
+ return false;
96
+ return now.slice(nowSep + 1) !== recordedStamp.slice(sep + 1);
23
97
  }
98
+ export const _startStamp = startStamp; // tests
24
99
  function recover(file) {
25
100
  const l = file + ".lock";
26
101
  try {
@@ -36,7 +111,18 @@ function recover(file) {
36
111
  finally {
37
112
  d.closeSync();
38
113
  }
39
- if (!owner || !dead(Number(owner.split("-")[0])))
114
+ if (!owner)
115
+ return;
116
+ let stamp;
117
+ try {
118
+ const st = fs.lstatSync(path.join(l, owner));
119
+ if (st.size > 0 && st.size <= 256)
120
+ stamp = fs.readFileSync(path.join(l, owner), "utf8").trim() || undefined;
121
+ }
122
+ catch {
123
+ return;
124
+ }
125
+ if (!dead(Number(owner.split("-")[0]), stamp))
40
126
  return;
41
127
  releaseLock(file, owner);
42
128
  }
@@ -66,7 +152,15 @@ export function takeLock(file, tryMs = TRY_MS) {
66
152
  const until = Date.now() + tryMs;
67
153
  try {
68
154
  fs.mkdirSync(tmp, { mode: 0o700 });
69
- fs.closeSync(fs.openSync(path.join(tmp, token), fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW, 0o600));
155
+ const ofd = fs.openSync(path.join(tmp, token), fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW, 0o600);
156
+ try {
157
+ const stamp = myStamp(); // K.9: who holds this pid, so a later process given the same pid is told apart
158
+ if (stamp)
159
+ fs.writeSync(ofd, stamp + "\n");
160
+ }
161
+ finally {
162
+ fs.closeSync(ofd);
163
+ }
70
164
  for (;;) {
71
165
  try {
72
166
  fs.renameSync(tmp, l); // replaces an empty recovered directory, never a live nonempty one
package/dist/settings.js CHANGED
@@ -10,7 +10,7 @@
10
10
  // Risk key is shown only as set or not set.
11
11
  import os from "node:os";
12
12
  import path from "node:path";
13
- import { ConfigError, DEFAULT_ANCHORING, DEFAULT_CALENDARS, DEFAULT_DOORS, DEFAULT_LIMITS, DEFAULT_SAVING, parseAnchoring, parseCalendars, KNOWN_KEYS, parseAgentStyle, parseDoors, parseKeyFile, parseSafeBrowsing, parseSaving, parseScanner, parseSignatureAgent, parseTranslator, readConfigObject, } from "./config.js";
13
+ import { parseChoice, ConfigError, DEFAULT_ANCHORING, DEFAULT_CALENDARS, DEFAULT_DOORS, DEFAULT_LIMITS, DEFAULT_SAVING, parseAnchoring, parseCalendars, KNOWN_KEYS, parseAgentStyle, parseDoors, parseKeyFile, parseSafeBrowsing, parseSaving, parseScanner, parseSignatureAgent, parseTranslator, readConfigObject, } from "./config.js";
14
14
  import { defaultKeyFile } from "./safebrowsing.js";
15
15
  import { DEFAULT_RENDER, parseRender } from "./render.js";
16
16
  import { MAX_SPACING_S, MIN_SPACING_S, candidates, loadSites, normalizeSite, parsePortList, parseSiteRule, parseSites } from "./sites.js";
@@ -35,6 +35,10 @@ const onOff = (name) => (s) => {
35
35
  throw new ConfigError(`"${name}" takes on or off.`);
36
36
  };
37
37
  export const DEFS = [
38
+ { name: "get_form_actions", default: "read", description: 'Reading a URL matching a GET form action seen on its source page: "read" reads it normally; "slip" requires a submit_form slip. Rendered scripts may never request the GET form actions on that page.', check: (v) => parseChoice("get_form_actions", v), fromText: (v) => parseChoice("get_form_actions", v) },
39
+ { name: "private_spacing", default: "shared", description: 'Private calls and form previews: "shared" writes origin and times only to share spacing across processes; "none" writes nothing and separate processes do not space these calls against each other.', check: (v) => parseChoice("private_spacing", v), fromText: (v) => parseChoice("private_spacing", v) },
40
+ { name: "hook_secrets", default: "hidden", description: 'Scanner and translator environment: "hidden" removes Tiresias secret variables; "inherit" passes the full owner environment, including those secrets.', check: (v) => parseChoice("hook_secrets", v), fromText: (v) => parseChoice("hook_secrets", v) },
41
+ { name: "text_views", default: "marked", description: 'Text views: "marked" keeps them readable with a marker before web content; "wrapped" wraps the text inside untrusted_content, like JSON. Agents should use JSON output.', check: (v) => parseChoice("text_views", v), fromText: (v) => parseChoice("text_views", v) },
38
42
  { name: "doors", default: DEFAULT_DOORS, description: 'How a first read of a site treats its door checks (llms.txt, MCP, API): "background" returns the page at once and checks them afterwards; "wait" checks them first (slower).', check: parseDoors, fromText: parseDoors },
39
43
  { name: "rendering", default: DEFAULT_RENDER, description: 'Running a page\'s JavaScript (W-10), in the installed Google Chrome, sandboxed and throwaway, with every request it makes going through Tiresias\'s rules: "off" never; "ask" when a read asks for it; "auto" also when a plain read is an empty JavaScript shell. TIRESIAS_RENDERING overrides it.', check: parseRender, fromText: parseRender },
40
44
  { name: "saving", default: DEFAULT_SAVING, description: 'Keeping a signed snapshot of a page a read asks to save (W-28): "off" never; "ask" when a read asks for it (read --save, or save on the MCP read). Snapshots are kept in this profile\'s saved/ folder; see tiresias saved.', check: parseSaving, fromText: parseSaving },
@@ -84,7 +88,7 @@ const SITE_DEF = new Map(SITE_DEFS.map((d) => [d.name, d]));
84
88
  const ENV = [
85
89
  { name: "TIRESIAS_HOME", default: "~/.tiresias", description: "The store folder (shared by every agent pointed at it)." },
86
90
  { name: "TIRESIAS_PROFILE", default: "default", description: "The profile to use when --profile is not given." },
87
- { name: "TIRESIAS_PRIVATE", default: "off", description: "1 makes the whole session private: nothing about any visit is saved." },
91
+ { name: "TIRESIAS_PRIVATE", default: "off", description: "1 makes the whole session private: no page records are saved; minimal politeness state still applies." },
88
92
  { name: "TIRESIAS_SAFE_BROWSING", default: "on", description: "0 turns the Safe Browsing check off for the session." },
89
93
  { name: "TIRESIAS_ALLOW_PORTS", default: "none", description: 'More ports to allow on every site, like "8080,9000-9100".' },
90
94
  { name: "TIRESIAS_MAX_BYTES", default: String(5 * 1024 * 1024), description: "The most bytes of a page that are read." },
@@ -353,7 +357,7 @@ export function confirmNow(name, rest, priv, confirm) {
353
357
  if (priv)
354
358
  throw new ConfigError(PRIVATE);
355
359
  if (!name || !isRisky(name))
356
- throw new ConfigError("Usage: tiresias settings confirm <risky setting> [<site>] --confirm \"...\". Risky settings: saving, rendering, translator, scanner, anchoring, anchor_calendars, safe_browsing, and the site settings ports, spacing_seconds, never_visit, hand_off.");
360
+ throw new ConfigError("Usage: tiresias settings confirm <risky setting> [<site>] --confirm \"...\". Risky settings: private_spacing, hook_secrets, saving, rendering, translator, scanner, anchoring, anchor_calendars, safe_browsing, and the site settings ports, spacing_seconds, never_visit, hand_off.");
357
361
  const site = SITE_DEF.has(name) ? siteArgs(name, rest, false).site : undefined;
358
362
  if (!site && rest.length)
359
363
  throw new ConfigError(`Usage: tiresias settings confirm ${name} --confirm "..."`);
package/dist/shelf.js CHANGED
@@ -130,7 +130,7 @@ export function clean(x) {
130
130
  url: c(o.url, MAX_URL_LOG), final_url: c(o.final_url, MAX_URL_LOG),
131
131
  ...str("declared_type", 200), ...str("declared_name", 255),
132
132
  agent: typeof o.agent === "string" ? c(o.agent, 200) : "unknown",
133
- ...(o.source === "provided_by_person" ? { source: "provided_by_person" } : {}),
133
+ ...(o.source === "provided_by_person" || o.source === "provided_by_agent" ? { source: o.source } : {}),
134
134
  };
135
135
  if (cut)
136
136
  r.cut = true;
package/dist/slips.js CHANGED
@@ -36,7 +36,7 @@ import { SlipError } from "./errors.js";
36
36
  import { PATH_RE, pathAllowed } from "./forms.js";
37
37
  import { readItem, writeItem } from "./itemfiles.js";
38
38
  import * as history from "./history.js";
39
- import { ensureSlipKey, readSlipKey } from "./keys.js";
39
+ import { SLIP_KEY_FILE, ensureSlipKey, readSlipKey, replaceSlipKey } from "./keys.js";
40
40
  import { NOFOLLOW, NONBLOCK, cliSafeId, isPrivate, ownFile, profileName, rmRegular, subDir } from "./store.js";
41
41
  export { SlipError };
42
42
  // The fixed allow-list of actions. v0.4 has exactly one.
@@ -491,6 +491,35 @@ export function revokeAll(priv = false) {
491
491
  removeLooseUse(d, f);
492
492
  return n;
493
493
  }
494
+ // ---- v1.1 workstream 4: rotating the slip key ----
495
+ // A new slip key makes every existing slip fail its signature check, so the rotation revokes them all, cleanly and
496
+ // on the record (revoked.jsonl), before the key is replaced, and once more after it (a slip granted meanwhile was
497
+ // signed by the old key). Saved pages are not touched: the old key's public half is kept for `saved verify`.
498
+ // Receipts never reference the slip key (a receipt names a snapshot by its SHA-256 id). An irreversible action, so
499
+ // it always needs its phrase, even with confirmations for risky settings turned off; the CLI also asks a person at
500
+ // a terminal to type "rotate slip key", like `slip revoke --all`. Written to history (tool "keys").
501
+ export const ROTATE_SLIP_PHRASE = "YES, ROTATE THE SLIP KEY";
502
+ export function checkRotatePhrase(confirm) {
503
+ if (confirm !== ROTATE_SLIP_PHRASE)
504
+ throw new SlipError(`Rotating the slip key revokes every permission slip of this profile, and saved pages signed before it are then checked against the old key's public half. It needs the exact confirmation ${JSON.stringify(ROTATE_SLIP_PHRASE)}. Run it again with: tiresias keys rotate --slips --confirm '${ROTATE_SLIP_PHRASE}' (type it exactly, in capitals; it is recorded in history). Nothing was changed.`);
505
+ }
506
+ export function rotateSlipKey(confirm, priv = false, now = Date.now()) {
507
+ if (priv || isPrivate())
508
+ throw new SlipError("Private mode: nothing is written, so the slip key is not rotated.");
509
+ checkRotatePhrase(confirm);
510
+ const d = subDir("keys", false);
511
+ if (!d || !fs.lstatSync(path.join(d, SLIP_KEY_FILE), { throwIfNoEntry: false }))
512
+ throw new SlipError("There is no slip key yet, so there is nothing to rotate. One is made by the first slip grant or saved page.");
513
+ // The slips are revoked inside replaceSlipKey, after every refusal (synced folder, another rotation, a full retired
514
+ // list), so a refused rotation never destroys them (Codex K.4).
515
+ let revoked = 0;
516
+ const r = replaceSlipKey(now, () => {
517
+ revoked = revokeAll(priv);
518
+ });
519
+ revoked += revokeAll(priv);
520
+ history.record({ time: new Date(now).toISOString(), tool: "keys", url: "", agent: "cli", status: "ok", door: "none", event: "slip_key_rotated", revoked, by: process.stdin.isTTY === true ? "terminal" : "not_terminal" });
521
+ return { revoked, retired: r.retired };
522
+ }
494
523
  // A use file is deleted on its own only when its slip file is confirmed gone at that moment. A slip
495
524
  // granted (and claimed) after any listing was made still has its <id>.json, so its uses are never
496
525
  // touched (Codex round 49: a final sweep deleted a new slip's use and gave the use back). Uses only
@@ -687,3 +716,16 @@ export function claimSlip(action, url, label, opts = {}) {
687
716
  }
688
717
  return no("no_slip");
689
718
  }
719
+ // A claimed use stays spent, but may leave the queue only while its slip still permits this target.
720
+ export function claimedStillValid(claim, action, url) {
721
+ const t = target(url);
722
+ const d = subDir("slips", false);
723
+ if (!d || !t || !pathAllowed(url) || !PATH_RE.test(t.pathname))
724
+ return false;
725
+ const keys = readSlipKey();
726
+ const profile = profileName();
727
+ const s = readOne(d, claim.slip_id, keys, profile);
728
+ return !!s && s !== "damaged" && s.action === action && s.site === t.origin && pathCovers(s.path, t.pathname)
729
+ && Date.parse(s.expires_at) > Date.now() && claim.use >= 1 && claim.use <= s.uses
730
+ && useVerifies(d, s.id, claim.use, keys, profile);
731
+ }
package/dist/store.js CHANGED
@@ -8,7 +8,8 @@ import fs from "node:fs";
8
8
  import os from "node:os";
9
9
  import path from "node:path";
10
10
  import readline from "node:readline";
11
- import { TiresiasError } from "./errors.js";
11
+ import { StringDecoder } from "node:string_decoder";
12
+ import { FetchError, TiresiasError } from "./errors.js";
12
13
  export const NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
13
14
  // Added to every file open: a pipe planted where a file should be then fails at once instead of
14
15
  // hanging the process. It changes nothing for ordinary files.
@@ -410,7 +411,7 @@ export function readJson(file) {
410
411
  }
411
412
  }
412
413
  // v0.5.1: private mode fails CLOSED in the store itself, not only at each call site: writeJson and
413
- // appendLine refuse inside a private call; the one exception is the Retry-After cooldown line.
414
+ // appendLine refuse inside a private call except for Retry-After. hosts.ts writes only shared politeness state.
414
415
  export const PRIVATE_WRITE = "Private mode: Tiresias writes nothing to the store in a private call.";
415
416
  export class PrivateWriteError extends TiresiasError {
416
417
  kind = "private_write";
@@ -486,7 +487,68 @@ export function readOwnedFile(file, maxBytes = 1024 * 1024) {
486
487
  }
487
488
  export const randomTmp = (file) => `${file}.${randomBytes(8).toString("hex")}.tmp`;
488
489
  export const MAX_LOG_READ = 8 * 1024 * 1024;
489
- // Read a JSONL log synchronously (used for cooldowns). Missing, foreign or
490
+ // Replay a fixed snapshot in bounded chunks, then only appended bytes. An old line may still be a
491
+ // site's rule, so start over only when the file is replaced or shrinks. Unreadable fails at the caller.
492
+ export function scanLogSync(name, take, cursor) {
493
+ const h = readBase(scopeOf(name));
494
+ if (!h)
495
+ return;
496
+ const file = path.join(h, name);
497
+ let fd;
498
+ try {
499
+ fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW | NONBLOCK);
500
+ }
501
+ catch (e) {
502
+ if (e.code === "ENOENT")
503
+ return;
504
+ throw e;
505
+ }
506
+ try {
507
+ ownFile(fd, file);
508
+ const { size, dev, ino } = fs.fstatSync(fd);
509
+ if (!cursor || cursor.dev !== dev || cursor.ino !== ino || size < cursor.offset) {
510
+ cursor = { dev, ino, offset: 0, pending: "", decoder: new StringDecoder("utf8") };
511
+ }
512
+ if (size === cursor.offset)
513
+ return cursor;
514
+ const buf = Buffer.alloc(64 * 1024);
515
+ const decoder = cursor.decoder;
516
+ let pending = cursor.pending;
517
+ const line = (raw) => {
518
+ if (!raw.trim())
519
+ return;
520
+ let entry;
521
+ try {
522
+ entry = JSON.parse(raw);
523
+ }
524
+ catch {
525
+ return;
526
+ }
527
+ take(entry);
528
+ };
529
+ for (let offset = cursor.offset; offset < size;) {
530
+ const n = fs.readSync(fd, buf, 0, Math.min(buf.length, size - offset), offset);
531
+ if (!n)
532
+ throw new Error("Cooldown log changed while reading.");
533
+ offset += n;
534
+ pending += decoder.write(buf.subarray(0, n));
535
+ let start = 0, end;
536
+ while ((end = pending.indexOf("\n", start)) >= 0) {
537
+ line(pending.slice(start, end));
538
+ start = end + 1;
539
+ }
540
+ pending = pending.slice(start);
541
+ if (pending.length > 64 * 1024)
542
+ throw new Error("Cooldown record is too large.");
543
+ }
544
+ line(pending); // a complete final record counts even without a newline
545
+ return { dev, ino, offset: size, pending, decoder }; // keep a partial record for the next append
546
+ }
547
+ finally {
548
+ fs.closeSync(fd);
549
+ }
550
+ }
551
+ // Read a bounded tail of a JSONL log. Missing, foreign or
490
552
  // symlinked files read as empty; damaged and blank lines are skipped.
491
553
  // A file over `maxBytes` is read from its LAST maxBytes only, starting at the
492
554
  // first full line after the cut, so a runaway log cannot stall a request.
@@ -591,7 +653,17 @@ export function appendLine(name, obj) {
591
653
  // Stream the log, never loading it whole. Matching lines are packed into pages
592
654
  // of at most `budget` bytes; only the requested page is kept in memory.
593
655
  // `names` may be several files (oldest first); they read as one log.
594
- export async function pageLog(names, keep, page = 1, budget = 40_000) {
656
+ export async function pageLog(names, keep, page = 1, budget = 40_000, scan = {}) {
657
+ const signal = scan.signal ?? callContext.getStore()?.signal;
658
+ const deadline = scan.deadline ?? Date.now() + 60_000;
659
+ let expired = false;
660
+ const check = () => {
661
+ if (signal?.aborted)
662
+ throw new FetchError("The request was cancelled.", "cancelled");
663
+ if (expired || Date.now() >= deadline)
664
+ throw new FetchError("The log scan took too long.", "timeout");
665
+ };
666
+ check();
595
667
  const out = { items: [], page, pages: 0, total: 0 };
596
668
  const h = readHome();
597
669
  if (!h)
@@ -599,6 +671,7 @@ export async function pageLog(names, keep, page = 1, budget = 40_000) {
599
671
  let cur = 0;
600
672
  let bytes = 0;
601
673
  for (const name of Array.isArray(names) ? names : [names]) {
674
+ check();
602
675
  const file = path.join(h, name);
603
676
  let fd;
604
677
  try {
@@ -607,35 +680,56 @@ export async function pageLog(names, keep, page = 1, budget = 40_000) {
607
680
  catch {
608
681
  continue;
609
682
  }
683
+ let size;
610
684
  try {
611
685
  ownFile(fd, file);
686
+ size = fs.fstatSync(fd).size;
612
687
  }
613
688
  catch {
614
689
  fs.closeSync(fd); // do not leak the descriptor when the file is rejected
615
690
  continue;
616
691
  }
617
- const rl = readline.createInterface({ input: fs.createReadStream(file, { fd, autoClose: true }), crlfDelay: Infinity });
618
- for await (const line of rl) {
619
- if (!line.trim())
620
- continue;
621
- let obj;
622
- try {
623
- obj = JSON.parse(line);
624
- }
625
- catch {
626
- continue; // skip a damaged line rather than lose the whole log
627
- }
628
- if (!keep(obj))
629
- continue;
630
- out.total++;
631
- const size = Buffer.byteLength(line, "utf8"); // UTF-8 bytes, not characters (Codex round 38)
632
- if (cur === 0 || bytes + size > budget) {
633
- cur++;
634
- bytes = 0;
692
+ if (!size) {
693
+ fs.closeSync(fd);
694
+ continue;
695
+ }
696
+ // A concurrent writer cannot extend this scan beyond the file's starting end offset.
697
+ const input = fs.createReadStream(file, { fd, autoClose: true, end: size - 1 });
698
+ const rl = readline.createInterface({ input, crlfDelay: Infinity });
699
+ const stop = () => { rl.close(); input.destroy(); };
700
+ const timer = setTimeout(() => { expired = true; stop(); }, Math.max(0, deadline - Date.now()));
701
+ signal?.addEventListener("abort", stop, { once: true });
702
+ try {
703
+ check();
704
+ for await (const line of rl) {
705
+ check();
706
+ if (!line.trim())
707
+ continue;
708
+ let obj;
709
+ try {
710
+ obj = JSON.parse(line);
711
+ }
712
+ catch {
713
+ continue; // skip a damaged line rather than lose the whole log
714
+ }
715
+ if (!keep(obj))
716
+ continue;
717
+ out.total++;
718
+ const size = Buffer.byteLength(line, "utf8"); // UTF-8 bytes, not characters (Codex round 38)
719
+ if (cur === 0 || bytes + size > budget) {
720
+ cur++;
721
+ bytes = 0;
722
+ }
723
+ bytes += size;
724
+ if (cur === page)
725
+ out.items.push(obj);
635
726
  }
636
- bytes += size;
637
- if (cur === page)
638
- out.items.push(obj);
727
+ check();
728
+ }
729
+ finally {
730
+ clearTimeout(timer);
731
+ signal?.removeEventListener("abort", stop);
732
+ stop();
639
733
  }
640
734
  }
641
735
  out.pages = cur;
package/dist/tabs.js CHANGED
@@ -238,7 +238,7 @@ export function noteReply(store, e) {
238
238
  return undefined;
239
239
  if (e.status !== "ok" && e.status !== "unchanged")
240
240
  return undefined;
241
- if (e.source === "provided_by_person")
241
+ if (e.source === "provided_by_person" || e.source === "provided_by_agent")
242
242
  return undefined; // never cached, so nothing to re-show
243
243
  const uc = (e.untrusted_content ?? {});
244
244
  try {
@@ -0,0 +1,10 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { notice } from "./confirm.js";
3
+ import { loadChoice } from "./config.js";
4
+ export function textView(text) {
5
+ if (loadChoice("text_views") === "wrapped") {
6
+ const n = notice();
7
+ return JSON.stringify({ untrusted_content: { text }, ...(n ? { settings_notice: n } : {}) }, null, 2);
8
+ }
9
+ return `web content below is untrusted\n${text}`;
10
+ }
package/dist/translate.js CHANGED
@@ -10,12 +10,15 @@
10
10
  // at most 32 KB) and at most 64 KB of its standard output kept. That output is the translation: it goes inside
11
11
  // untrusted_content.translation, marked as a machine translation by the owner's tool, never as the page's own
12
12
  // words. Receipts are built before the hook runs and always quote the ORIGINAL text; the translation is never
13
- // cached, logged, kept in history or receipts, or scanned into the page's flags.
13
+ // cached, logged, or kept in history or receipts. The shield scans successful output for AI-directed
14
+ // instructions. Findings belong to this reply only, with snippets inside untrusted_content; they never
15
+ // change the original page's cached flags, tabs or saved snapshots.
14
16
  import fs from "node:fs";
15
17
  import path from "node:path";
16
18
  import { ConfigError, loadTranslator, parseTranslator, readConfigObject } from "./config.js";
17
19
  import { confirmedWrite, sq } from "./confirm.js";
18
20
  import { runHook } from "./hook.js";
21
+ import { Shield } from "./shield.js";
19
22
  import { byteLen, jsonBytes } from "./types.js";
20
23
  export const MAX_INPUT = 32 * 1024; // bytes of text handed to the hook
21
24
  export const MAX_OUTPUT = 64 * 1024; // bytes of its output kept
@@ -32,6 +35,7 @@ export function parseTarget(v) {
32
35
  export const NOTE = "A machine translation of the text above, made by the owner's own translation tool. It is not the page's own words and may be wrong; every receipt quotes the original text, never this.";
33
36
  const MSG_OK = "A translation by the owner's own tool is in untrusted_content.translation; receipts quote the original text.";
34
37
  const MSG_NOT = "No translation was made (see translation.reason). The page is shown in its own language.";
38
+ const TRANSLATION_WHERE = "machine translation";
35
39
  // The text a reply shows, as plain lines: the title, then the outline's headings and previews, a section's text,
36
40
  // or the passages and their headings.
37
41
  export function shownText(uc) {
@@ -129,6 +133,16 @@ export async function translateReply(e, wanted) {
129
133
  uc.translation = { text, note: NOTE };
130
134
  e.untrusted_content = uc;
131
135
  set({ status: "ok", by, from, to, ...cut });
136
+ const shield = new Shield();
137
+ shield.scan(text, TRANSLATION_WHERE);
138
+ const flags = shield.flags.filter((f) => f.type === "ai_directed_instruction");
139
+ if (flags.length) {
140
+ // env() may share the original page's flag array with the cache. Never append to it in place.
141
+ uc.flag_details = [...(uc.flag_details ?? []), ...flags];
142
+ e.flags = [...new Set([...e.flags, ...flags.map((f) => f.type)])];
143
+ if (e.counts)
144
+ e.counts.flags += flags.length; // details, not distinct codes (as in env())
145
+ }
132
146
  fitTranslation(e);
133
147
  }
134
148
  // Saving adds metadata after the hook; check again once that metadata is in place too.
@@ -136,8 +150,14 @@ export function fitTranslation(e) {
136
150
  if (e.translation?.status !== "ok" || jsonBytes(e) <= HARD_LIMIT)
137
151
  return;
138
152
  const uc = e.untrusted_content;
139
- if (uc)
153
+ if (uc) {
140
154
  delete uc.translation;
155
+ // Keep the finding even when its text cannot fit; say exactly which evidence was omitted.
156
+ if (Array.isArray(uc.flag_details))
157
+ uc.flag_details = uc.flag_details.map((f) => f.detail?.startsWith(TRANSLATION_WHERE)
158
+ ? { ...f, detail: `${f.detail}; translation omitted from this reply for size` }
159
+ : f);
160
+ }
141
161
  e.message = (e.message ?? "").replace(MSG_OK, MSG_NOT);
142
162
  e.translation = { ...e.translation, status: "failed", reason: "too_large" };
143
163
  }
package/dist/types.js CHANGED
@@ -1,8 +1,8 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
2
  // Shared shapes. The envelope matches SPEC section 6.1.
3
- export const VERSION = "1.0.1";
3
+ export const VERSION = "1.1.0";
4
4
  // Bump when the reader changes what it extracts, so older cached pages are re-read.
5
- export const PARSER_VERSION = 15; // 15: v1.0.1 reader fixes. 14: v0.9.1 sweep ("(JSON)" heading generated, list indentation capped at 8 levels, markdown code kept as preformatted, nesting past 256 flattened). 13: v0.9 labels Tiresias makes ("(top of page)", "(structured data)") are marked generated, never quoted. 12: v0.7 language (W-26). 11: v0.6 calendar events (ics.ts). 10: v0.5.1 JSON as line blocks, W-22 reader. 9: W-20 file kinds (scripts, CSV, calendars and contacts read as plain text; SVG; file flags)
5
+ export const PARSER_VERSION = 16; // 16: v1.1.0 form recognition (cached form listings carry not_allowed). 15: v1.0.1 reader fixes. 14: v0.9.1 sweep ("(JSON)" heading generated, list indentation capped at 8 levels, markdown code kept as preformatted, nesting past 256 flattened). 13: v0.9 labels Tiresias makes ("(top of page)", "(structured data)") are marked generated, never quoted. 12: v0.7 language (W-26). 11: v0.6 calendar events (ics.ts). 10: v0.5.1 JSON as line blocks, W-22 reader. 9: W-20 file kinds (scripts, CSV, calendars and contacts read as plain text; SVG; file flags)
6
6
  export const MAX_URL = 2048; // longer URLs are omitted (and counted), never shortened;
7
7
  // Points at Raibit's page on raibit.ai, which links to the GitHub repo once it is public; it stays (Travis,
8
8
  // SPEC section 9, 2026-11-01).
package/dist/watchflow.js CHANGED
@@ -175,7 +175,6 @@ export async function watch(ctx = DEFAULT, page) {
175
175
  : "No bookmarks are watched. Add one with bookmark add <name> <url> --watch.",
176
176
  notice: NOTICE,
177
177
  counts,
178
- attention,
179
178
  ...(page === undefined ? {} : { page }),
180
179
  pages: page === undefined ? 1 : pages,
181
180
  untrusted_content: null,
@@ -185,7 +184,7 @@ export async function watch(ctx = DEFAULT, page) {
185
184
  const build = () => {
186
185
  const rs = rcpts.flat();
187
186
  report.counts.receipts = rs.length;
188
- const uc = { ...(changed.length ? { changed } : {}), ...(rs.length ? { receipts: rs } : {}), ...(attentionUrls.length ? { attention_urls: attentionUrls } : {}) };
187
+ const uc = { ...(attention.length ? { attention } : {}), ...(changed.length ? { changed } : {}), ...(rs.length ? { receipts: rs } : {}), ...(attentionUrls.length ? { attention_urls: attentionUrls } : {}) };
189
188
  report.untrusted_content = Object.keys(uc).length ? uc : null;
190
189
  };
191
190
  build();
package/dist/work.js CHANGED
@@ -9,7 +9,7 @@ import { diffSections } from "./diff.js";
9
9
  import { languageOf } from "./lang.js";
10
10
  import { inspect } from "./inside.js";
11
11
  import { normalizeList } from "./safelist.js";
12
- import { holdsSecret } from "./echo.js";
12
+ import { holdsSecret, SecretWithheld } from "./echo.js";
13
13
  import { approxTextLength, detectWall } from "./walls.js";
14
14
  export function handle(job) {
15
15
  const done = handleJob(job);
@@ -82,11 +82,13 @@ export async function handleAsync(job) {
82
82
  return handle(job);
83
83
  try {
84
84
  const { parsePdf } = await import("./pdf.js");
85
- const parsed = await parsePdf(job.bytes, job.url);
85
+ const parsed = await parsePdf(job.bytes, job.url, job.secrets);
86
86
  parsed.language = languageOf(parsed, job.lang); // W-26 (v0.7)
87
87
  return { result: { parsed, wall: null } };
88
88
  }
89
89
  catch (e) {
90
+ if (e instanceof SecretWithheld)
91
+ return { error: "secret_withheld" };
90
92
  if (e instanceof PdfError)
91
93
  return { error: "pdf", message: e.message };
92
94
  if (e instanceof ComplexityError)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@raibitsi/tiresias",
3
- "version": "1.0.1",
3
+ "version": "1.1.0",
4
4
  "description": "The honest browser for AI agents. The browser you never open.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Raibit (https://raibit.ai/)",