rvlib-shipkit 2.2.0 → 2.4.0

package/src/agent-time/timeline.ts

@@ -0,0 +1,218 @@
+// The time math of one transcript stream (a session, or one sub-agent run):
+// how long each tool call took, and where the wall time went.
+//
+// The constraint a reader breaks first: parallel calls overlap. A call's own
+// time is end minus start, and a sum of those is CALL time, which can exceed
+// the wall. The wall is cut once, by a sweep over every boundary, so a second
+// of wall lands in exactly one bucket.
+import type { Outcome } from '../reflect/transcript.ts'
+
+export type Call = {
+    id: string
+    start: number
+    /** null while its result has not arrived (a live call, or one never answered) */
+    end: number | null
+    tool: string
+    shape: string
+    cmd: string
+    outcome: Outcome | null
+    code: number | null
+    /** it waited for the human to allow it */
+    approval: boolean
+    /** how it was allowed (transcript.ts Perm) */
+    perm: string
+    /** it only read (turns.ts isReadOnly, judged when indexed) */
+    read: boolean
+}
+
+export type Mark = { at: number; kind: 'prompt' | 'wake' | 'message' | 'reply' }
+
+export type Stream = { calls: Call[]; marks: Mark[] }
+
+/** where a slice of wall time went */
+export type Bucket = 'model' | 'tools' | 'approval' | 'subagent' | 'background' | 'human' | 'idle'
+
+export type Breakdown = Record<Bucket, number>
+
+/** a wait on him longer than this is the session parked, not a wait */
+export const IDLE_MS = 30 * 60 * 1000
+
+export const emptyBreakdown = (): Breakdown => ({ model: 0, tools: 0, approval: 0, subagent: 0, background: 0, human: 0, idle: 0 })
+
+/** a foreground sub-agent call: the session waits on another agent's work */
+export const isAgentCall = (c: Call): boolean => c.tool === 'Agent' || c.tool === 'Task'
+
+/** the first value of a sorted list above `t`, by bisection */
+function firstAfter(sorted: number[], t: number): number | undefined {
+    let lo = 0
+    let hi = sorted.length
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1
+        if ((sorted[mid] as number) <= t) lo = mid + 1
+        else hi = mid
+    }
+    return sorted[lo]
+}
+
+/** the end every call is measured to: its result, else the next prompt or wake
+ *  after it (the human moved on, so it was interrupted), else the stream's last
+ *  event. `open` says the end was inferred */
+export type Closed = Call & { stop: number; open: boolean }
+
+/** sorted by start */
+export function closeCalls(s: Stream): Closed[] {
+    const turns = s.marks.filter((m) => m.kind !== 'reply').map((m) => m.at).sort((a, b) => a - b)
+    let last = 0
+    for (const m of s.marks) if (m.at > last) last = m.at
+    for (const c of s.calls) if ((c.end ?? c.start) > last) last = c.end ?? c.start
+    return s.calls
+        .map((c): Closed => {
+            if (c.end != null) return { ...c, stop: Math.max(c.start, c.end), open: false }
+            const next = firstAfter(turns, c.start)
+            return { ...c, stop: next ?? last, open: true }
+        })
+        .sort((a, b) => a.start - b.start)
+}
+
+/** the call's own duration in ms */
+export const callMs = (c: { start: number; stop: number }): number => Math.max(0, c.stop - c.start)
+
+type Point = { at: number; d: 'start' | 'stop' | Mark['kind']; lane: 'tool' | 'agent' | 'approval'; ix: number }
+
+/** the wall of one stream cut into buckets, clipped to [from, to]. Between two
+ *  boundaries: a tool in flight → tools; only calls waiting for his allow →
+ *  approval; only a sub-agent in flight → subagent;
+ *  nothing in flight and the next thing is his prompt → human (idle past
+ *  IDLE_MS); the next thing is a wake (a task notification, a hand-back) →
+ *  background; a message relayed in counts as a prompt (a sub-agent that
+ *  handed back sits parked until the coordinator or he writes to it); anything else → the model was working.
+ *
+ *  `turnModel` (one slot per closed call) receives the model stretch that
+ *  ended in each call: the turn that issued it, split evenly over the calls
+ *  of one batch. A stretch that ends in his prompt or a wake was the final
+ *  reply and goes to no call */
+export function wallBreakdown(s: Stream, from = -Infinity, to = Infinity, idleMs = IDLE_MS, closed: Closed[] = closeCalls(s), turnModel?: Float64Array): Breakdown {
+    const out = emptyBreakdown()
+    const points: Point[] = []
+    closed.forEach((c, ix) => {
+        const lane = isAgentCall(c) ? 'agent' : c.approval ? 'approval' : 'tool'
+        points.push({ at: c.start, d: 'start', lane, ix }, { at: c.stop, d: 'stop', lane, ix })
+    })
+    for (const m of s.marks) points.push({ at: m.at, d: m.kind, lane: 'tool', ix: -1 })
+    points.sort((a, b) => a.at - b.at)
+    let tools = 0
+    let agents = 0
+    let approvals = 0
+    let pending = 0
+    const issued: number[] = []
+    let i = 0
+    while (i < points.length) {
+        const at = (points[i] as Point).at
+        issued.length = 0
+        let ended = false
+        while (i < points.length && (points[i] as Point).at === at) {
+            const p = points[i] as Point
+            const n = p.d === 'start' ? 1 : p.d === 'stop' ? -1 : 0
+            if (p.lane === 'agent') agents += n
+            else if (p.lane === 'approval') approvals += n
+            else tools += n
+            if (p.d === 'start') issued.push(p.ix)
+            else if (p.d === 'prompt' || p.d === 'wake' || p.d === 'message') ended = true
+            i++
+        }
+        if (turnModel != null) {
+            if (issued.length > 0) for (const ix of issued) turnModel[ix] = (turnModel[ix] ?? 0) + pending / issued.length
+            if (issued.length > 0 || ended) pending = 0
+        }
+        if (i >= points.length) break
+        const nextAt = (points[i] as Point).at
+        const a = Math.max(at, from)
+        const b = Math.min(nextAt, to)
+        if (b <= a) continue
+        const len = b - a
+        let bucket: Bucket
+        if (tools > 0) bucket = 'tools'
+        else if (approvals > 0) bucket = 'approval'
+        else if (agents > 0) bucket = 'subagent'
+        else {
+            let next = i
+            let prompt = false
+            let wake = false
+            while (next < points.length && (points[next] as Point).at === nextAt) {
+                const d = (points[next] as Point).d
+                if (d === 'prompt' || d === 'message') prompt = true
+                if (d === 'wake') wake = true
+                next++
+            }
+            const gap = nextAt - at
+            bucket = prompt ? (gap > idleMs ? 'idle' : 'human') : wake ? 'background' : 'model'
+        }
+        out[bucket] += len
+        if (bucket === 'model') pending += len
+    }
+    return out
+}
+
+export const addBreakdown = (into: Breakdown, b: Breakdown): Breakdown => {
+    for (const k of Object.keys(into) as Bucket[]) into[k] += b[k]
+    return into
+}
+
+/** a failed call is retried when the next call of the same shape in the
+ *  stream comes within this window */
+export const RETRY_MS = 10 * 60 * 1000
+
+export const FAILED: ReadonlySet<Outcome> = new Set<Outcome>(['exit', 'error', 'timeout'])
+
+export type Retry = { failed: Closed; next: Closed; blind: boolean }
+
+/** every failed call followed by the same shape again: `blind` when the
+ *  command is the exact same text, so nothing changed between the two.
+ *  `calls` sorted by start (closeCalls) */
+export function retries(calls: Closed[]): Retry[] {
+    const out: Retry[] = []
+    const nextOfShape = new Map<string, Closed>()
+    for (let i = calls.length - 1; i >= 0; i--) {
+        const c = calls[i] as Closed
+        const next = nextOfShape.get(c.shape)
+        nextOfShape.set(c.shape, c)
+        if (c.outcome == null || !FAILED.has(c.outcome)) continue
+        if (next == null || next.start - c.stop > RETRY_MS) continue
+        out.push({ failed: c, next, blind: next.cmd.trim() === c.cmd.trim() })
+    }
+    return out.reverse()
+}
+
+/** a call that ran longer than this before a complaint is not looked for */
+const LOOKBACK_MS = 3 * 60 * 60 * 1000
+
+/** what the agent ran in the minutes before `at`: calls in flight at that
+ *  moment or started in the window, cut at `at`, longest first. `calls`
+ *  sorted by start (closeCalls) */
+export function ranBefore(calls: Closed[], at: number, windowMs = 10 * 60 * 1000): Closed[] {
+    let lo = 0
+    let hi = calls.length
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1
+        if ((calls[mid] as Closed).start <= at) lo = mid + 1
+        else hi = mid
+    }
+    const out: Closed[] = []
+    for (let i = lo - 1; i >= 0; i--) {
+        const c = calls[i] as Closed
+        if (c.start < at - LOOKBACK_MS) break
+        if (c.stop >= at - windowMs) out.push({ ...c, stop: Math.min(c.stop, at) })
+    }
+    return out.sort((a, b) => callMs(b) - callMs(a))
+}
+
+/** p in [0, 1] of a list of ms, nearest rank */
+export function quantile(xs: number[], p: number): number {
+    return quantileSorted([...xs].sort((a, b) => a - b), p)
+}
+
+/** the same over a list already sorted ascending */
+export function quantileSorted(s: number[], p: number): number {
+    if (s.length === 0) return 0
+    return s[Math.min(s.length - 1, Math.max(0, Math.ceil(p * s.length) - 1))] ?? 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/assets/kits/identity-kit.ts

@@ -16,6 +16,7 @@ import { dirname, join } from 'path'
 import sharp from 'sharp'
 import { defineKind, type CanvasGen, type ComfyGen, type Kind } from '../kit-config.ts'
 import { HOUSE_FAMILIES, type TrailerLookInput } from '../../trailer/look.ts'
+import type { TrailerSoundInput } from '../../trailer/sound/brand.ts'
 
 export type Brand = {
     name: string
@@ -31,8 +32,10 @@ export type Brand = {
      *  name/tagline right); the hook owns compositing the mark if it wants one */
     drawOg?: (ctx: SKRSContext2D, brand: Brand, size: { w: number; h: number }) => void
     /** the look every trailer of the repo wears (titles, card, face, logo);
-     *  each value left out is derived from the palette (trailer/look.ts) */
-    trailer?: TrailerLookInput
+     *  each value left out is derived from the palette (trailer/look.ts);
+     *  its sound section (`comfy`, `elevenKey`, `voice`, `voices`) makes the
+     *  voice, sfx and music lines (trailer/sound/brand.ts) */
+    trailer?: TrailerLookInput & TrailerSoundInput
 }
 
 export const FAVICON_SIZE = 512

package/src/cli/cmd_Commands.ts

@@ -17,6 +17,11 @@ 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'
+    words?: Record<string, unknown>
+    stamp?: string[]
     /** listed on the essentials page */
     essential?: Essential
     /** what a kit row runs */
@@ -76,6 +81,10 @@ 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.words != null) row.words = m.words
+                if (m.stamp != null) row.stamp = m.stamp
                 if (m.essential != null) row.essential = m.essential
                 const v = ROW_OF.get(c)
                 if (v != null) row.runs = runText(v.run)