@manyoars/oars 0.4.1 → 0.5.1

package/dist/sessions/pi.d.ts

@@ -2,6 +2,14 @@
 export declare const piRoot: (env: {
     [name: string]: string | undefined;
 }, home?: string) => string;
+/**
+ * The folder the reader reads Pi sessions from. The user's own `PI_CODING_AGENT_SESSION_DIR` wins when set and non-empty: Pi writes session files straight into it, with no per-project
+ * subfolder (session-manager.ts:1766-1768, main.ts:749-753), and lists only the `.jsonl` files directly in it (listSessionsFromDir, session-manager.ts:942-955). Otherwise it is `sessions/`
+ * under the agent folder, whose files sit in `--<cwd>--` subfolders. `--session-dir` and the `sessionDir` setting are not read by this reader.
+ */
+export declare const piSessionsDir: (env: {
+    [name: string]: string | undefined;
+}, home?: string) => string;
 type Obj = {
     [key: string]: unknown;
 };
@@ -20,6 +28,8 @@ export interface PiStore {
     sessions: PiSession[];
     /** The session as transcript text for `captureSession`; throws when the file cannot be read or holds no parseable line. */
     transcript: (session: PiSession) => Promise<string>;
+    /** True when the file holds only its header and entries that carry no turn (`piHeadOnly`); `sessions verify` counts such a file as empty, not unreadable. */
+    headOnly: (session: PiSession) => Promise<boolean>;
     /** Files skipped because their id is not a safe file name (it names a skeleton), counted so the skip is never silent. */
     rejected: number;
     /** Sessions that could not be inspected, reported once each and never fatal; the reason names no path. */
@@ -30,7 +40,9 @@ export interface PiStore {
 }
 /** The non-blank lines that are not JSON (a torn write), kept so `captureSession` counts them and the deposit line reports them. */
 export declare const piBadLines: (text: string) => string[];
+export declare const piHeadOnly: (text: string) => boolean;
 /** One session as the lines `captureSession` reads. */
 export declare const piLines: (text: string, fallbackId: string) => Obj[];
-export declare const openPiStore: (root: string) => Promise<PiStore | undefined>;
+/** `base` is the sessions folder (`piSessionsDir`): its subfolders hold the files Pi groups by project, and a `.jsonl` file directly in it is one Pi wrote to a session folder the user chose. */
+export declare const openPiStore: (base: string) => Promise<PiStore | undefined>;
 export {};

package/dist/sessions/pi.js

@@ -5,9 +5,9 @@
 // reader is original. No vendor text promises the format (docs/session-format.md names the file version and says an older file is migrated when loaded, and sends programs to the SDK),
 // so `docs/sessions-store.md` says what a live run would still have to prove.
 //
-// Where it reads from (`piRoot`): `$PI_CODING_AGENT_DIR`, else `~/.pi/agent` (`%USERPROFILE%\.pi\agent` on Windows) (src/config.ts:610, :613-614, :630-636, docs/environment-variables.md:81). A session is
+// Where it reads from (`piSessionsDir`): `$PI_CODING_AGENT_SESSION_DIR` when set (a flat folder of session files, session-manager.ts:942-955, main.ts:749-753), else `sessions/` under (`piRoot`): `$PI_CODING_AGENT_DIR`, else `~/.pi/agent` (`%USERPROFILE%\.pi\agent` on Windows) (src/config.ts:610, :613-614, :630-636, docs/environment-variables.md:81). A session is
 // `sessions/--<cwd with its leading separator removed and / \ : turned into ->--/<ISO time with : . turned into ->_<session id>.jsonl` (docs/session-format.md:10-14,
-// session-manager.ts:590-593). The sessions folder can be moved by `--session-dir`, `PI_CODING_AGENT_SESSION_DIR`, or a setting (docs/sessions.md:60); this reader does not follow those.
+// session-manager.ts:590-593). `--session-dir` and the `sessionDir` setting can also move it (docs/sessions.md:60); this reader does not follow those.
 // A file is written only once a conversation exists, then appended to (session-manager.ts:1176-1190). Line 1 is the header and every later line is an entry:
 //   session           {version, id, timestamp, cwd, parentSession?}: `version` is the FILE format's (1 linear, 2 tree, 3 `hookMessage` renamed `custom`), not Pi's; no app version is recorded.
 //                     The session's cwd is fixed (docs/sessions.md:15): a `cd` inside a command is not tracked, and a resume from another folder runs in this one.
@@ -29,13 +29,22 @@
 import { open, readdir, readFile, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, join, posix, win32 } from 'node:path';
+import { holdsOnlyKinds } from './head-only.js';
+/** Pi expands a leading ~ in its path settings (config.ts:614, utils/paths.ts:134-137). */
+const expandHome = (path, home) => (path === '~' ? home : /^~[/\\]/.test(path) ? join(home, path.slice(2)) : path);
 /** The Pi agent folder for an environment; a test passes its own so it never reads the real one. */
 export const piRoot = (env, home = homedir()) => {
     const set = env.PI_CODING_AGENT_DIR;
-    if (set === undefined || set === '')
-        return join(home, '.pi', 'agent');
-    // Pi expands a leading ~ (config.ts:614).
-    return set === '~' ? home : /^~[/\\]/.test(set) ? join(home, set.slice(2)) : set;
+    return set === undefined || set === '' ? join(home, '.pi', 'agent') : expandHome(set, home);
+};
+/**
+ * The folder the reader reads Pi sessions from. The user's own `PI_CODING_AGENT_SESSION_DIR` wins when set and non-empty: Pi writes session files straight into it, with no per-project
+ * subfolder (session-manager.ts:1766-1768, main.ts:749-753), and lists only the `.jsonl` files directly in it (listSessionsFromDir, session-manager.ts:942-955). Otherwise it is `sessions/`
+ * under the agent folder, whose files sit in `--<cwd>--` subfolders. `--session-dir` and the `sessionDir` setting are not read by this reader.
+ */
+export const piSessionsDir = (env, home = homedir()) => {
+    const set = env.PI_CODING_AGENT_SESSION_DIR;
+    return set === undefined || set === '' ? join(piRoot(env, home), 'sessions') : expandHome(set, home);
 };
 const isObj = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const str = (value) => (typeof value === 'string' && value !== '' ? value : undefined);
@@ -62,6 +71,9 @@ const reasonOf = (error, file) => (error instanceof Error ? error.message : Stri
 const missing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
 /** The non-blank lines that are not JSON (a torn write), kept so `captureSession` counts them and the deposit line reports them. */
 export const piBadLines = (text) => text.split('\n').filter((raw) => raw.trim() !== '' && parse(raw) === undefined);
+/** The session header and the ten entry kinds the format defines that carry no turn (the list at the top of this file). A file of them alone is a session started and quit. */
+const PI_HEAD_KINDS = new Set(['session', 'model_change', 'thinking_level_change', 'usage', 'compaction', 'branch_summary', 'custom', 'custom_message', 'context_edit', 'label', 'session_info']);
+export const piHeadOnly = (text) => holdsOnlyKinds(text, PI_HEAD_KINDS);
 /** A time in milliseconds, or undefined when it is not an absolute time after 2000. */
 const MIN_MS = Date.parse('2000-01-01T00:00:00Z');
 const absoluteMs = (ms) => (ms !== undefined && ms >= MIN_MS ? ms : undefined);
@@ -291,8 +303,8 @@ const firstLine = async (file) => {
         await handle.close();
     }
 };
-export const openPiStore = async (root) => {
-    const base = join(root, 'sessions');
+/** `base` is the sessions folder (`piSessionsDir`): its subfolders hold the files Pi groups by project, and a `.jsonl` file directly in it is one Pi wrote to a session folder the user chose. */
+export const openPiStore = async (base) => {
     const unreadable = [];
     let folders;
     try {
@@ -301,17 +313,18 @@ export const openPiStore = async (root) => {
     catch (error) {
         if (missing(error))
             return undefined;
-        return { sessions: [], transcript: () => Promise.reject(new Error('no sessions')), rejected: 0, unreadable: [{ file: base, reason: reasonOf(error, base) }] };
+        return { sessions: [], transcript: () => Promise.reject(new Error('no sessions')), headOnly: () => Promise.resolve(false), rejected: 0, unreadable: [{ file: base, reason: reasonOf(error, base) }] };
     }
     const sessions = [];
     let rejected = 0;
-    for (const folder of folders.filter((candidate) => candidate.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+    const places = [base, ...folders.filter((candidate) => candidate.isDirectory()).sort((a, b) => a.name.localeCompare(b.name)).map((folder) => join(base, folder.name))];
+    for (const dir of places) {
         let files;
         try {
-            files = await readdir(join(base, folder.name), { withFileTypes: true });
+            files = dir === base ? folders : await readdir(dir, { withFileTypes: true });
         }
         catch (error) {
-            unreadable.push({ file: join(base, folder.name), reason: reasonOf(error, join(base, folder.name)) });
+            unreadable.push({ file: dir, reason: reasonOf(error, dir) });
             continue;
         }
         for (const entry of files.filter((candidate) => candidate.isFile() && candidate.name.endsWith('.jsonl')).sort((a, b) => a.name.localeCompare(b.name))) {
@@ -322,7 +335,7 @@ export const openPiStore = async (root) => {
                 rejected += 1;
                 continue;
             }
-            const file = join(base, folder.name, entry.name);
+            const file = join(dir, entry.name);
             try {
                 const first = await firstLine(file);
                 const header = first === undefined ? undefined : parse(first);
@@ -344,6 +357,7 @@ export const openPiStore = async (root) => {
         sessions,
         rejected,
         unreadable,
+        headOnly: async (session) => piHeadOnly(await readFile(session.file, 'utf8')),
         transcript: async (session) => {
             const text = await readFile(session.file, 'utf8');
             const lines = [...piLines(text, session.id).map((line) => JSON.stringify(line)), ...piBadLines(text)];

package/dist/sessions/pool-books.d.ts

@@ -5,7 +5,7 @@ export declare const lastFetchedBundle: (storeDir: string) => Promise<Bundle | u
 export declare const booksLines: (bundle: Bundle | undefined) => string[];
 /** The totals as flat numbers for the health batch to read; a field with no source is null and never 0, and a bundle with no books gives null. */
 export interface BooksTotals {
-    /** Lineage (section 17 rule 6): the floor the served count was held to, the day it was as of, and the day the panel was counted, which a 304 can leave days old. */
+    /** Lineage (section 17 rule 6): the thresholded floor (`floors.public`; a clear cell is held to `floors.clear`) the served count was held to, the day it was as of, and the day the panel was counted, which a 304 can leave days old. */
     floor: number;
     asOfDay: string | null;
     panelDay: string | null;

package/dist/sessions/pool-books.js

@@ -25,7 +25,7 @@ const candidatesOf = async (storeDir) => {
 export const lastFetchedBundle = async (storeDir) => {
     const keys = await loadSignIns(storeDir, 'books');
     for (const { file, server, harness, version } of await candidatesOf(storeDir)) {
-        const key = keys.find((entry) => contentHash(entry.server) === server)?.signingKey;
+        const key = keys.find((entry) => contentHash(entry.server) === server)?.signingKeys;
         if (key === undefined || !isHarness(harness))
             continue;
         let parsed;

package/dist/sessions/pool-choices.d.ts

@@ -1,5 +1,7 @@
 import type { FolderSend, PoolChoices } from './store.js';
 export type Sends = 'all' | FolderSend;
 export declare const sendsOf: (choices: PoolChoices, project: string) => Sends;
-/** Whether a raw copy of this folder's sessions may be built: raw consent granted, and the folder neither skeleton only nor off. */
-export declare const rawAllowed: (choices: PoolChoices, project: string) => boolean;
+/** Whether a yes to the raw prompt is held back because it was given under another covenant than the one in force. With no version known (a build that asked no pool) nothing is held back: nothing leaves then, and the sender checks again. */
+export declare const rawStale: (choices: PoolChoices, version: string | undefined) => boolean;
+/** Whether a raw copy of this folder's sessions may be built: raw consent granted for the covenant in force, and the folder neither skeleton only nor off. */
+export declare const rawAllowed: (choices: PoolChoices, project: string, version?: string) => boolean;

package/dist/sessions/pool-choices.js

@@ -7,5 +7,7 @@ export const sendsOf = (choices, project) => {
         return 'off';
     return modes.includes('skeleton') ? 'skeleton' : 'all';
 };
-/** Whether a raw copy of this folder's sessions may be built: raw consent granted, and the folder neither skeleton only nor off. */
-export const rawAllowed = (choices, project) => choices.rawConsent === 'granted' && sendsOf(choices, project) === 'all';
+/** Whether a yes to the raw prompt is held back because it was given under another covenant than the one in force. With no version known (a build that asked no pool) nothing is held back: nothing leaves then, and the sender checks again. */
+export const rawStale = (choices, version) => choices.rawConsent === 'granted' && version !== undefined && choices.rawConsentVersion !== version;
+/** Whether a raw copy of this folder's sessions may be built: raw consent granted for the covenant in force, and the folder neither skeleton only nor off. */
+export const rawAllowed = (choices, project, version) => choices.rawConsent === 'granted' && !rawStale(choices, version) && sendsOf(choices, project) === 'all';

package/dist/sessions/pool-command.d.ts

@@ -2,6 +2,7 @@ import type { Outcome, RunDeps } from '../cli.js';
 import { CliError } from '../errors.js';
 import { Masker, type Outgoing } from './pool-print.js';
 import { isObject, loadSignIns, textIn, type SignIn } from './pool-replica.js';
+import { type MachineConfig } from './machine.js';
 import { type SessionsRuntime } from './store.js';
 import { type Git } from './survival.js';
 export declare const DEPOSIT = "pool-deposit";
@@ -34,10 +35,12 @@ interface Call {
     /** Set for a command that prints what it sends: the print comes first, with these secrets masked. */
     show?: Masker;
     /** A raw part is a PUT of bytes that are not JSON; every other call is a GET, or a POST when it has a body. */
-    method?: 'PUT';
+    method?: 'PUT' | 'DELETE';
     type?: string;
     /** Headers beyond the usual ones (the raw routes state their redaction and capture versions, and the raw consent). */
     extra?: Array<[string, string]>;
+    /** The answer's bytes are kept as bytes when it is a 200, not read as JSON: the person's own raw copy. */
+    binary?: boolean;
 }
 /** How a request leaves this machine. The command line passes none, so a send goes over the network (`networkSender`); a test passes one to read what would leave. */
 export type Sender = (request: Outgoing) => Promise<Reply>;
@@ -45,19 +48,33 @@ export type Sender = (request: Outgoing) => Promise<Reply>;
 export declare const ask: (deps: RunDeps, step: string, server: string, path: string, init: Call, via?: Sender) => Promise<Reply>;
 /** The sender `deposit --send` uses when none is given: the request goes out over the network as built. The loopback test passes it to read what reaches the socket. */
 export declare const networkSender: (deps: RunDeps, step: string) => Sender;
+/** The server's named refusal, as a failure: its `error` is the problem's code in `--json`. */
+export declare const refusal: (step: string, { status, body }: Reply) => CliError;
 /**
- * `oars pool login` (spec Section 1.4): the device flow runs here, against the provider, and the pool sees only the provider's token, once, and answers its own credential. Every request prints before it is sent, with the device code, the provider's token,
- * and the credential masked as `<credential: n bytes>`. A client ID, scope, grant type, and Google's `client_secret` print as they are: none is secret.
+ * `oars pool login` (spec Section 1.4): the pool runs the provider's device flow and this client only shows the code and polls the pool, so no provider token, device code, client ID, or secret is ever here. With `--verbose`, every request, which goes to the pool alone,
+ * prints before it is sent, with the login handle and the credential masked as `<credential: n bytes>`; without it, a failure's cause is the first line printed.
  */
 export declare const poolLogin: (deps: RunDeps, options: {
     server?: string | undefined;
     provider?: string | undefined;
+    verbose?: boolean;
 }) => Promise<Outcome>;
+/**
+ * `oars pool logout` (S8): revokes this machine's credential at the pool (`DELETE /v1/login`), then removes the local entry. A pool that cannot be reached does not keep the entry: the person asked to be signed out here, so the entry
+ * goes and the output says the credential was not revoked there (it lapses on its own, and a login past the pool's cap revokes the oldest). A refusal for any other reason keeps the entry, so the command can be run again.
+ */
+export declare const poolLogout: (deps: RunDeps, options: {
+    server?: string | undefined;
+}) => Promise<Outcome>;
+/** A person is here when input and the screen's stream are both terminals: a typed phrase counts only for a text that reached a screen. */
+export declare const isTerminal: (deps: RunDeps) => boolean;
+/** The next line a person types, or `undefined` when the input ends first. The interface is closed after it, so the terminal is released. */
+export declare const lineFrom: (input: NodeJS.ReadableStream) => Promise<string | undefined>;
 export declare const vocabularyExpired: (deps: RunDeps) => CliError | undefined;
 /** One batch to the pool: a batch past one request's bytes goes in parts, in order, each answered 202 until the last completes the deposit with 201. A part sent again is harmless, so the retry covers every part alike. */
 export declare const postBatch: (deps: RunDeps, options: {
     server: string;
-    token: string;
+    token: string | undefined;
     bytes: string;
     hash: string;
     via: Sender;
@@ -72,19 +89,27 @@ export declare const postRaw: (deps: RunDeps, options: {
     hash: string;
     body: string;
     bytes: number;
+    consent: string;
     via: Sender;
 }) => Promise<void>;
+/** The exclusion terms in force now, re-read from the term file each time it is asked: empty when the file is missing or unreadable. */
+export declare const currentTerms: (deps: RunDeps) => Promise<string[]>;
+/** The outbox key, and the skeleton `id`, of a machine's session: from the environment's session salt (per account, not per machine), else its own name standing in for the account, which a machine has none of. The holding route names its branch by the same key. */
+export declare const machineKeyOf: (machine: MachineConfig, session: string) => string;
 /**
- * `oars pool deposit`: every session in the store that passes both session gates is built into a canonical batch in the outbox, and the command stops: nothing is sent. The gates run before any projection does: the folder
+ * `oars pool deposit`: every session in the store that passes both session gates is built into a canonical batch in the outbox, and the command stops: no session data is sent. The gates run before any projection does: the folder
  * allowlist, then the exclusion check. A session that fails either, or has no raw to scan, is counted and never built. A session is built only once it has ended: no transcript of it, main or subagent, has gained a line (the later of its capture
  * and its raw file's last write) for `session_idle_hours` (6 hours). One that has not is counted under `notEnded`, and any batch of it from an earlier pass is withdrawn. `--send <hash>` is the lock in `sendBatch`.
  */
 export declare const poolDeposit: (deps: RunDeps, options: {
     server?: string | undefined;
     acceptCovenant?: string | undefined;
+    inEuEeaUk?: string | undefined;
     send?: string | undefined;
     via?: Sender | undefined;
     git?: Git | undefined;
+    session?: string | undefined;
+    covenant?: string | undefined;
 }) => Promise<Outcome>;
 /** `oars pool outbox`: prints each batch as it would be sent (a batch past one request prints each part's request, in order), the request line and every header included, with the bearer credential as its size and nothing else masked, then its SHA-256, and records that it was shown. `--explain` adds each field's rule. */
 export declare const poolOutbox: (deps: RunDeps, options: {
@@ -97,8 +122,10 @@ export declare const poolFetch: (deps: RunDeps, options: {
     harness?: string | undefined;
     harnessVersion: string;
 }) => Promise<Outcome>;
-/** The raw prompt, in plain words: shown by `oars pool raw` until it is answered, and what the nightly send relies on. Redaction is best effort and the text says so. */
+/** The raw prompt, in plain words: shown by `oars pool raw` until it is answered, and what the detached sender relies on. Redaction is best effort and the text says so. */
 export declare const RAW_PROMPT: string;
+/** What a person types to say yes to the raw prompt: consent is a statement made at a terminal (GDPR Articles 7 and 9(2)(a)), not a flag a script can pass. */
+export declare const RAW_PHRASE = "I consent to sending raw copies";
 /** `oars pool raw`: shows the raw prompt and the answer so far; `--consent yes|no` records the answer; `--folder <entry> --mode all|skeleton|off` sets what one folder may send. */
 export declare const poolRaw: (deps: RunDeps, options: {
     consent?: string | undefined;
@@ -113,3 +140,16 @@ export declare const poolCoverage: (deps: RunDeps, options: {
     orgSize?: string | undefined;
     repoVisibility?: string | undefined;
 }) => Promise<Outcome>;
+/**
+ * `oars pool prove`: the account proves control of itself with its sign-in token alone (`POST /v1/account/proof`, never a machine key), and the pool stores the time. It prints the account and the time to send, in reply to the operator's request for proof, so the operator can compare them with the stored row (GDPR Art. 12(6)). A lapsed sign-in says to run `oars pool login` first; a closed account proves by that login instead.
+ */
+export declare const poolProve: (deps: RunDeps, options: {
+    server?: string | undefined;
+}) => Promise<Outcome>;
+/** `oars pool export`: the person's own copy of what the pool holds about their account, saved to a folder (GDPR Articles 15(3) and 20). It follows the pool's cursor page by page and keeps each page as a file; with `raw` it also fetches each raw object the ledger lists that still stands. It writes nothing to the pool. A failed page stops the walk (there is no cursor past it); a failed object does not stop the others. Every failure is named in the error, with what was saved. */
+export declare const poolExport: (deps: RunDeps, options: {
+    server?: string | undefined;
+    out: string;
+    raw?: boolean | undefined;
+    via?: Sender | undefined;
+}) => Promise<Outcome>;