rvlib-shipkit 2.2.0 → 2.3.0

package/src/agent-time/turns.ts

@@ -0,0 +1,135 @@
+// Turn count: what makes an agent slow when no command is. Every tool call
+// costs a model turn before it, so an agent that reads one file per turn
+// spends its wall on the model, not on the reads. The two questions this
+// module answers on pure data: was a call a single read, and did it go out in
+// parallel with the one before it.
+//
+// The constraint a reader breaks first: a read is judged on the WHOLE command,
+// never on its shape alone. `grep -l x | xargs sed -i` shapes as `grep`, and
+// it writes.
+import { stripHeredocs } from './shape.ts'
+import type { Closed } from './timeline.ts'
+
+/** bumped with any read rule below: the index judges every stored call again */
+export const READ_VERSION = 1
+
+/** tools that only read */
+export const READ_TOOLS: ReadonlySet<string> = new Set(['Read', 'Grep', 'Glob'])
+
+/** Bash shapes that only read (shape.ts names them). `sed` without `-i` prints;
+ *  `sed -i` is shaped `sed -i (edit)` and `cat > f` is `cat > (write)`, so
+ *  neither is here */
+export const READ_SHAPES: ReadonlySet<string> = new Set(['grep', 'rg', 'git grep', 'sed', 'cat', 'ls', 'head', 'tail', 'wc', 'find', 'git status', 'git log', 'git diff', 'git show'])
+
+/** words a read command may carry beside its read: scene setting, loop and
+ *  test words, a filter it pipes into, a print */
+const BESIDE = new Set([
+    'cd', 'pushd', 'popd', 'export', 'set', 'true', ':', 'time', 'for', 'do', 'done', 'while', 'if', 'then', 'else', 'fi', '[', '[[', 'test',
+    'echo', 'printf', 'pwd', 'uptime', 'date', 'which', 'basename', 'dirname', 'realpath', 'stat', 'file', 'du', 'tree', 'diff',
+    'sort', 'uniq', 'cut', 'tr', 'nl', 'column', 'jq', 'awk', 'xargs', 'grep', 'egrep', 'rg', 'head', 'tail', 'wc', 'cat', 'sed', 'ls', 'find', 'git',
+])
+
+/** a find action that writes or runs something */
+const FIND_ACTS = /\s-(?:delete|exec|execdir|ok|okdir|fprint0?|fprintf|fls)\b/
+
+/** git subcommands that only read */
+const GIT_READS = new Set(['status', 'log', 'diff', 'show', 'grep', 'ls-files', 'ls-tree', 'rev-parse', 'rev-list', 'merge-base', 'cat-file', 'describe', 'shortlog', 'branch', 'blame'])
+
+/** the parts of a command line: statements and every pipeline part, quoted
+ *  text blanked (a pattern is never a separator nor a redirect) */
+const parts = (command: string): string[] =>
+    (command.includes('<<') ? stripHeredocs(command) : command)
+        .replace(/\\\n/g, ' ')
+        .replace(/'[^']*'|"(?:[^"\\]|\\.)*"/g, '""')
+        .split(/&&|\|\||[;\n|]|(?<![>&])&(?![>&])/)
+
+/** an output redirect to a file: `> f`, `>> f`, `&> f`; `2>&1` and
+ *  `> /dev/null` write nothing */
+const writesFile = (part: string): boolean => {
+    for (const m of part.matchAll(/>{1,2}\s*([^\s>]*)/g)) {
+        const target = m[1] ?? ''
+        if (target === '' || target.startsWith('&') || target === '/dev/null' || target.startsWith('/dev/std')) continue
+        return true
+    }
+    return false
+}
+
+/** the words of a part after env assignments and a leading `X=$(` */
+const HEAD = /^[\s(]*(?:[A-Za-z_][A-Za-z0-9_]*=(?:\$\(|\S*\s+))*(\S+)\s*(.*)$/s
+
+/** one part of the line reads only */
+function partReads(part: string, whole: string): boolean {
+    if (writesFile(part)) return false
+    if (/^\s*[A-Za-z_][A-Za-z0-9_]*=\S*\s*$/.test(part)) return true
+    const m = HEAD.exec(part)
+    if (m == null) return true
+    const head = (m[1] as string).replace(/^.*\//, '').replace(/\)+$/, '')
+    const rest = ` ${m[2] ?? ''}`
+    if (!BESIDE.has(head)) return false
+    if (head === 'sed') return !/\s-[a-zA-Z]*i|\s--in-place/.test(rest)
+    if (head === 'find') return !FIND_ACTS.test(rest)
+    if (head === 'awk') return !/system\(|print[^;'"]*>/.test(whole)
+    if (head === 'xargs') return partReads(rest.replace(/^(?:\s+-\S+(?:\s+\d+)?)*/, ''), whole)
+    if (head === 'git') return GIT_READS.has(/^(?:\s+-[Cc]\s+\S+|\s+-\S+)*\s+(\S+)/.exec(rest)?.[1] ?? '')
+    if (head === 'do' || head === 'then' || head === 'else') return rest.trim() === '' || partReads(rest, whole)
+    return true
+}
+
+/** the call only read: a read tool, or a Bash command of a read shape (a for
+ *  loop over one included) whose every part reads */
+export function isReadOnly(c: { tool: string; shape: string; cmd: string }): boolean {
+    if (READ_TOOLS.has(c.tool)) return true
+    if (c.tool !== 'Bash' || !READ_SHAPES.has(c.shape.replace(/^\(for\) /, ''))) return false
+    return parts(c.cmd).every((p) => p.trim() === '' || partReads(p, c.cmd))
+}
+
+/** a call issued this soon after the one before, while that one still ran,
+ *  went out in the same turn */
+export const PARALLEL_MS = 2000
+
+/** one flag per call (sorted by start, closeCalls): it started before the
+ *  previous call ended, within PARALLEL_MS of its start */
+export function parallelFlags(calls: readonly Closed[]): boolean[] {
+    return calls.map((c, i) => {
+        const prev = calls[i - 1]
+        return prev != null && c.start < prev.stop && c.start - prev.start <= PARALLEL_MS
+    })
+}
+
+/** the turn metrics of a set of streams */
+export type TurnStats = { calls: number; reads: number; parallel: number; model: number }
+
+export const emptyTurns = (): TurnStats => ({ calls: 0, reads: 0, parallel: 0, model: 0 })
+
+export const addTurns = (into: TurnStats, t: TurnStats): TurnStats => {
+    into.calls += t.calls
+    into.reads += t.reads
+    into.parallel += t.parallel
+    into.model += t.model
+    return into
+}
+
+/** what a read shape costs in model turns: its calls, and the model time of
+ *  the turns that issued them */
+export type ReadCost = { shape: string; calls: number; model: number }
+
+/** a read call's name in the cost table: its tool, or its Bash shape */
+export const readName = (c: { tool: string; shape: string }): string => (c.tool === 'Bash' ? c.shape : c.tool)
+
+/** the turns of one stream: `model` is its model bucket, `turnModel` the
+ *  per call share wallBreakdown filled; read calls add to `costs` */
+export function turnsOf(calls: readonly Closed[], model: number, turnModel: Float64Array, costs: Map<string, ReadCost>): TurnStats {
+    const par = parallelFlags(calls)
+    const t: TurnStats = { calls: calls.length, reads: 0, parallel: 0, model }
+    calls.forEach((c, i) => {
+        if (par[i]) t.parallel++
+        if (!c.read) return
+        t.reads++
+        const name = readName(c)
+        const row = costs.get(name) ?? { shape: name, calls: 0, model: 0 }
+        row.calls++
+        row.model += turnModel[i] ?? 0
+        costs.set(name, row)
+    })
+    return t
+}

package/src/cli/cmd_Commands.ts

@@ -17,6 +17,9 @@ export type CommandRow = {
     examples: [string, string][]
     /** a filmable command (cli/kit/verb.ts): takes --out, a clip also --seconds */
     film?: Film
+    /** a filmable command's take version and length (build/trailer.md, Film lines) */
+    version?: number | string
+    length?: 'own'
     /** listed on the essentials page */
     essential?: Essential
     /** what a kit row runs */
@@ -76,6 +79,8 @@ export function commandRows(plain: Definition[], detailed: Definition[] = [], bi
             if (c != null) {
                 const m = marksOf(c)
                 if (m.film != null) row.film = m.film
+                if (m.version != null) row.version = m.version
+                if (m.length != null) row.length = m.length
                 if (m.essential != null) row.essential = m.essential
                 const v = ROW_OF.get(c)
                 if (v != null) row.runs = runText(v.run)