@deniscodp/skills 0.0.0-stage → 1.0.0

package/skills/denisco-workflow-benchmark/scripts/state-prompt.mjs

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { rejectSymlinkPath } from './io.mjs';
+
+const START = '<!-- workflow:next-prompt:start -->';
+const END = '<!-- workflow:next-prompt:end -->';
+const normalize = text => text.replace(/\r\n/g, '\n');
+
+function decode(bytes) {
+  let encoding = 'utf-8', bom = Buffer.alloc(0);
+  if (bytes.subarray(0, 3).equals(Buffer.from([0xef, 0xbb, 0xbf]))) bom = bytes.subarray(0, 3);
+  else if (bytes.subarray(0, 2).equals(Buffer.from([0xff, 0xfe]))) { bom = bytes.subarray(0, 2); encoding = 'utf-16le'; }
+  else if (bytes.subarray(0, 2).equals(Buffer.from([0xfe, 0xff]))) { bom = bytes.subarray(0, 2); encoding = 'utf-16be'; }
+  const text = new TextDecoder(encoding, { fatal: true, ignoreBOM: true }).decode(bytes.subarray(bom.length));
+  return { text, encode(value) {
+    const body = Buffer.from(value, encoding === 'utf-8' ? 'utf8' : 'utf16le');
+    if (encoding === 'utf-16be') body.swap16();
+    return Buffer.concat([bom, body]);
+  } };
+}
+
+function section(text) {
+  const starts = [...text.matchAll(/<!-- workflow:next-prompt:start/g)];
+  const ends = [...text.matchAll(/<!-- workflow:next-prompt:end/g)];
+  if (!starts.length && !ends.length) return null;
+  if (starts.length !== 1 || ends.length !== 1) throw new Error('Malformed or duplicate next-prompt markers in STATE; no files changed');
+  const start = starts[0].index, end = ends[0].index;
+  if (!text.startsWith(START, start) || !text.startsWith(END, end) || end <= start
+      || (start && text[start - 1] !== '\n')
+      || !['\r', '\n'].includes(text[start + START.length])
+      || text[end - 1] !== '\n'
+      || (end + END.length < text.length && !['\r', '\n'].includes(text[end + END.length]))) {
+    throw new Error('Malformed next-prompt markers in STATE; no files changed');
+  }
+  return { start, end: end + END.length, text: text.slice(start, end + END.length) };
+}
+
+function readState(file) {
+  rejectSymlinkPath(file);
+  if (!fs.statSync(file).isFile()) throw new Error(`Expected STATE file: ${file}`);
+  const bytes = fs.readFileSync(file);
+  return { bytes, ...decode(bytes) };
+}
+
+function rendered(prompt, contextHash) {
+  // A path can contain backticks: use a fence longer than any run in the prompt.
+  const fence = '`'.repeat(Math.max(3, ...[...prompt.matchAll(/`+/g)].map(m => m[0].length + 1)));
+  return `${START}\n## Next-session prompt\n\n<!-- workflow:next-prompt:context ${contextHash} -->\n${fence}text\n${prompt}${fence}\n${END}`;
+}
+
+export function checkStatePrompt({ state, block, prompt, contextHash }) {
+  const saved = section(readState(state).text);
+  const valid = saved !== null && normalize(saved.text) === rendered(prompt, contextHash);
+  return { state, block, valid, status: !saved ? 'missing' : valid ? 'saved' : 'stale-or-modified',
+    prompt: valid ? prompt : null };
+}
+
+export function updateStatePrompt({ state, block, prompt, contextHash, clear = false, validateContext }) {
+  const original = readState(state), saved = section(original.text);
+  const eol = original.text.includes('\r\n') ? '\r\n' : '\n';
+  const replacement = clear ? '' : rendered(prompt, contextHash).replace(/\n/g, eol);
+  let text;
+  if (saved) text = original.text.slice(0, saved.start) + replacement + original.text.slice(saved.end);
+  else if (clear) text = original.text;
+  else {
+    const separator = !original.text.length || original.text.endsWith(eol + eol) ? '' : original.text.endsWith(eol) ? eol : eol + eol;
+    text = original.text + separator + replacement + eol;
+  }
+  const updated = original.encode(text), changed = !original.bytes.equals(updated);
+  const lock = `${state}.lock`;
+  rejectSymlinkPath(lock);
+  const fd = fs.openSync(lock, 'wx');
+  let temporary;
+  try {
+    validateContext();
+    if (!readState(state).bytes.equals(original.bytes)) throw new Error('STATE changed during prompt update; retry after review');
+    if (changed) {
+      temporary = `${state}.${crypto.randomUUID()}.tmp`;
+      fs.writeFileSync(temporary, updated, { flag: 'wx', mode: fs.statSync(state).mode });
+      // Detect a non-cooperating editor while the temporary file was prepared.
+      validateContext();
+      if (!readState(state).bytes.equals(original.bytes)) throw new Error('STATE changed during prompt update; retry after review');
+      fs.renameSync(temporary, state);
+    }
+    if (!readState(state).bytes.equals(updated)) throw new Error('STATE changed after prompt update; delivery is not confirmed');
+    validateContext();
+    if (clear) return { state, block: null, changed, valid: true, status: 'cleared', prompt: null };
+    const checked = checkStatePrompt({ state, block, prompt, contextHash });
+    if (!checked.valid) throw new Error('Saved prompt failed read-back verification');
+    return { ...checked, changed };
+  } finally {
+    if (temporary && fs.existsSync(temporary)) fs.unlinkSync(temporary);
+    fs.closeSync(fd);
+    fs.unlinkSync(lock);
+  }
+}

package/skills/denisco-workflow-benchmark/scripts/tracking.mjs

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { readJSON, writeNew, mutateRun, rejectSymlinkPath } from './io.mjs';
+import { whoami } from './discover.mjs';
+import { phases, registerSession } from './runs.mjs';
+import { benchPath, readWorkflow } from './workflow.mjs';
+import { snapshotConfiguration } from './configuration.mjs';
+
+const canonical = file => process.platform === 'win32' ? path.resolve(file).toLowerCase() : path.resolve(file);
+const nextCall = ticket => ({ executable: process.execPath, args: [benchPath(), 'track', '--ticket', ticket] });
+
+function record(ticket, data, status, reason = null, sessionKey = null) {
+  mutateRun(data.run, run => {
+    run.registrationAttempts ??= [];
+    const entry = { ticket, phase: data.phase, status, reason, sessionKey };
+    const index = run.registrationAttempts.findIndex(item => item.ticket === ticket);
+    if (index < 0) run.registrationAttempts.push(entry);
+    else run.registrationAttempts[index] = entry;
+  });
+  return { status, reason, sessionKey, ticket,
+    ...(data.configurationWarning ? { configurationWarning: data.configurationWarning } : {}),
+    ...(status === 'pending' ? { nextCall: nextCall(ticket) } : { closeArgs: ['--ticket', ticket, '--session-state', 'active'] }) };
+}
+
+// Two tool calls are necessary: the first output must reach the native transcript.
+// Tickets are agent-internal and must never be reused in another conversation.
+export function track({ handoff, provider, phase, root, ticket, from, to, parent, parentEvidence, configurationId, skillsRoot } = {}) {
+  if (!ticket) {
+    if (!['codex', 'claude'].includes(provider) || !phases.includes(phase)) throw new Error('Provide provider and phase');
+    if ((from && !Number.isFinite(Date.parse(from))) || (to && !Number.isFinite(Date.parse(to))) || (from && to && Date.parse(from) >= Date.parse(to))) throw new Error('Invalid tracking time bounds');
+    const { data, run, paths } = readWorkflow(handoff, { draft: true });
+    if (!run) return { status: 'not-enabled', measurement: data.measurement.status, instruction: 'Resolve setup from the task documents; preserve explicit disabled measurement.' };
+    if (configurationId && skillsRoot) throw new Error('Choose --configuration or --skills-root');
+    if (configurationId && !run.configurationHistory?.some(c => c.id === configurationId)) throw new Error('Unknown configuration ID');
+    let configurationSnapshot, configurationWarning;
+    if (!configurationId) {
+      try {
+        configurationSnapshot = snapshotConfiguration({
+          skillsRoot: skillsRoot ?? requestProviderRoot(run.project, provider) ?? path.resolve(path.dirname(benchPath()), '../..'),
+          note: 'Captured by track at entry to this conversation. Snapshot of the selected bundle (default: the executing helper bundle); installed files only, not proof of loading or of earlier session configuration. Check alternate skill sources and mixed-version resumes separately.'
+        });
+      } catch (error) { configurationWarning = `Configuration snapshot unavailable: ${error.message}`; }
+    }
+    const marker = `wftrack-${crypto.randomUUID()}`;
+    ticket = path.join(path.dirname(data.measurement.run), 'registrations', `${marker}.json`);
+    const request = { schemaVersion: 1, handoff: paths.handoff, run: data.measurement.run, runId: run.id,
+      provider, phase, marker, root: root ? path.resolve(root) : undefined, from, to, parent, parentEvidence, configurationId,
+      configurationSnapshot, configurationWarning };
+    writeNew(ticket, `${JSON.stringify(request, null, 2)}\n`);
+    return { ...record(ticket, request, 'pending', 'Waiting for the first tool output to reach the transcript.'), marker,
+      instruction: 'Execute nextCall in a separate tool call in this same conversation. Do not ask the user to fill identifiers or carry this ticket into a continuation prompt.' };
+  }
+  if ([handoff, provider, phase, root, from, to, parent, parentEvidence, configurationId, skillsRoot].some(value => value !== undefined)) throw new Error('--ticket cannot be combined with setup options');
+  ticket = path.resolve(ticket);
+  rejectSymlinkPath(ticket);
+  const lock = `${ticket}.lock`;
+  rejectSymlinkPath(lock);
+  const fd = fs.openSync(lock, 'wx');
+  try {
+    const request = readJSON(ticket);
+    if (request.schemaVersion !== 1 || !['codex', 'claude'].includes(request.provider) || !phases.includes(request.phase)) throw new Error('Invalid registration ticket');
+    const { data, run } = readWorkflow(request.handoff, { draft: true });
+    if (!run || canonical(data.measurement.run) !== canonical(request.run) || run.id !== request.runId) throw new Error('Registration binding changed; no session registered');
+    let identity;
+    try { identity = whoami({ provider: request.provider, project: run.project, nonce: request.marker, root: request.root }); }
+    catch (error) { return record(ticket, request, 'pending', error.message); }
+    const key = `${identity.provider}:${identity.sessionId}${identity.agentId ? `:${identity.agentId}` : ''}`;
+    const existing = run.sessions.find(session => session.key === key);
+    if (existing) {
+      if (canonical(existing.log) !== canonical(identity.log) || existing.from !== (request.from ?? null) || existing.to !== (request.to ?? null)
+          || existing.parent !== (request.parent ?? null) || (request.configurationId && existing.configurationId !== request.configurationId)) {
+        return record(ticket, request, 'pending', 'Existing session has different source, bounds, parent or configuration; review the attribution.');
+      }
+      // A conversation moving from planning to implementation is still one native session.
+      if (!existing.configurationId) request.configurationWarning = 'Existing session has no attributed configuration; a later snapshot cannot establish its earlier configuration. Review historical evidence.';
+      return record(ticket, request, 'registered', `Already registered under ${existing.phase}; preserved without double counting.`, key);
+    }
+    try {
+      registerSession(request.run, { provider: identity.provider, sessionId: identity.sessionId, agentId: identity.agentId,
+        log: identity.log, phase: request.phase, from: request.from, to: request.to, parent: request.parent,
+        parentEvidence: request.parentEvidence, configurationId: request.configurationId, configurationSnapshot: request.configurationSnapshot });
+    } catch (error) { return record(ticket, request, 'pending', error.message); }
+    return record(ticket, request, 'registered', null, key);
+  } finally { fs.closeSync(fd); fs.unlinkSync(lock); }
+}
+
+function requestProviderRoot(projectRoot, provider) {
+  const candidate = path.join(projectRoot, provider === 'claude' ? '.claude' : '.agents', 'skills');
+  return fs.existsSync(candidate) && fs.statSync(candidate).isDirectory() ? candidate : null;
+}

package/skills/denisco-workflow-benchmark/scripts/usage.mjs

@@ -0,0 +1,175 @@
+import fs from 'node:fs';
+import { hash } from './io.mjs';
+
+const validNumber = n => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+const n = value => validNumber(value) ? value : null;
+const keys = ['input', 'cacheRead', 'cacheWrite', 'output', 'reasoning', 'total'];
+const empty = () => Object.fromEntries(keys.map(key => [key, null]));
+function add(target, value) {
+  for (const key of keys) target[key] = target[key] === null || value[key] === null ? null : target[key] + value[key];
+}
+function normalizeCodex(u) {
+  return { input: n(u.input_tokens), cacheRead: n(u.cached_input_tokens),
+    cacheWrite: n(u.cache_write_input_tokens), output: n(u.output_tokens),
+    reasoning: n(u.reasoning_output_tokens), total: n(u.total_tokens) };
+}
+function normalizeClaude(u) {
+  const parts = [u.input_tokens, u.cache_read_input_tokens, u.cache_creation_input_tokens];
+  const input = parts.every(validNumber) ? parts.reduce((a, b) => a + b, 0) : null;
+  return { input, cacheRead: n(u.cache_read_input_tokens), cacheWrite: n(u.cache_creation_input_tokens),
+    output: n(u.output_tokens), reasoning: n(u.output_tokens_details?.reasoning_tokens),
+    total: input !== null && validNumber(u.output_tokens) ? input + u.output_tokens : null };
+}
+function parseLines(text) {
+  const warnings = [];
+  const lines = text.replace(/^\uFEFF/, '').split(/\r?\n/);
+  const records = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].trim()) continue;
+    try { records.push(JSON.parse(lines[i])); }
+    catch { warnings.push(i === lines.length - 1 ? 'Incomplete trailing JSON line; reimport after flush.' : `Malformed JSON at line ${i + 1}.`); }
+  }
+  return { records, warnings };
+}
+function inRange(time, from, to) {
+  const value = Date.parse(time);
+  return Number.isFinite(value) && (from === null || value >= from) && (to === null || value < to);
+}
+function boundary(value) {
+  if (!value) return null;
+  const time = Date.parse(value);
+  if (!Number.isFinite(time)) throw new Error(`Invalid ISO time: ${value}`);
+  return time;
+}
+
+function collectSkillInvocations(value, timestamp, out, seen = new Set()) {
+  if (!value || typeof value !== 'object' || seen.has(value)) return;
+  seen.add(value);
+  if (value.name === 'Skill') {
+    const skill = value.input?.skill ?? value.arguments?.skill ?? value.input?.name;
+    if (typeof skill === 'string') out.push({ skill, timestamp });
+  }
+  for (const child of Object.values(value)) collectSkillInvocations(child, timestamp, out, seen);
+}
+
+// A skill can also be loaded by typing its slash command, which leaves no Skill tool call.
+// The recorded name is the command as typed: it may be a CLI built-in rather than a skill.
+const COMMAND_OPEN = '<command-name>/', COMMAND_CLOSE = '</command-name>';
+const commandName = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$/;
+function collectCommandInvocations(value, timestamp, out, seen = new Set()) {
+  if (!value || typeof value !== 'object' || seen.has(value)) return;
+  seen.add(value);
+  for (const child of Object.values(value)) {
+    if (typeof child !== 'string') { collectCommandInvocations(child, timestamp, out, seen); continue; }
+    for (let at = child.indexOf(COMMAND_OPEN); at !== -1; at = child.indexOf(COMMAND_OPEN, at + COMMAND_OPEN.length)) {
+      const from = at + COMMAND_OPEN.length, to = child.indexOf(COMMAND_CLOSE, from);
+      const name = to === -1 ? null : child.slice(from, to).trim();
+      if (name && commandName.test(name)) out.push({ command: name, timestamp });
+    }
+  }
+}
+
+export function parseUsage(text, provider, options = {}) {
+  if (!['codex', 'claude'].includes(provider)) throw new Error('Provider must be codex or claude');
+  const { records, warnings } = parseLines(text);
+  const from = boundary(options.from), to = boundary(options.to);
+  if (from !== null && to !== null && from >= to) throw new Error('from must precede to');
+  const ids = new Set(), agents = new Set(), models = new Set(), versions = new Set(), efforts = new Set();
+  const times = [];
+  const requestKeys = [];
+  const skillInvocations = [], commandInvocations = [];
+  let usage = empty(), raw = {}, observed = 0;
+  let started = false;
+  const accumulate = value => { if (!started) { usage = value; started = true; } else add(usage, value); observed++; };
+  if (provider === 'codex') {
+    let previous = null;
+  for (const record of records) {
+      collectSkillInvocations(record, record.timestamp ?? null, skillInvocations);
+      collectCommandInvocations(record, record.timestamp ?? null, commandInvocations);
+      const p = record.payload ?? {};
+      if (record.type === 'session_meta') {
+        if (p.id ?? p.session_id) ids.add(p.id ?? p.session_id);
+        if (p.cli_version) versions.add(p.cli_version);
+      }
+      if (record.type === 'turn_context' && inRange(record.timestamp, from, to)) {
+        if (p.model) models.add(p.model);
+        if (p.effort) efforts.add(p.effort);
+      }
+      if (record.type !== 'event_msg' || p.type !== 'token_count' || !p.info?.total_token_usage) continue;
+      const current = normalizeCodex(p.info.total_token_usage);
+      const selected = inRange(record.timestamp, from, to);
+      if (selected) {
+        times.push(record.timestamp);
+        raw = Object.fromEntries(Object.entries(p.info.total_token_usage).filter(([, v]) => validNumber(v)));
+        if (previous) {
+          const delta = Object.fromEntries(keys.map(k => [k, current[k] === null || previous[k] === null ? null : current[k] - previous[k]]));
+          if (Object.values(delta).some(v => v !== null && v < 0)) {
+            warnings.push('Codex cumulative counter reset/decrease: usage after this point is incomplete; delimit the session.');
+          } else if (Object.values(delta).some(v => v > 0)) accumulate(delta);
+        } else if (from === null) accumulate(current);
+        else warnings.push('No preceding Codex counter at lower bound; first in-range usage omitted.');
+      }
+      previous = current;
+    }
+    if (from === null) warnings.push('Full-history import: confirm the log contains no inherited fork prefix or work for another task.');
+  } else {
+    const messages = new Map();
+    for (const record of records) {
+      collectSkillInvocations(record, record.timestamp ?? null, skillInvocations);
+      collectCommandInvocations(record, record.timestamp ?? null, commandInvocations);
+      if (record.sessionId ?? record.session_id) ids.add(record.sessionId ?? record.session_id);
+      if (record.agentId) agents.add(record.agentId);
+      if (!record.message?.usage) continue;
+      const message = record.message;
+      if (!message.id) { warnings.push('Claude usage without message ID omitted.'); continue; }
+      const selected = inRange(record.timestamp, from, to);
+      if (selected) {
+        if (record.version) versions.add(record.version);
+        if (record.effort) efforts.add(record.effort);
+        if (message.model) models.add(message.model);
+        times.push(record.timestamp);
+      }
+      const key = message.id;
+      const clean = {};
+      for (const field of ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens']) {
+        if (validNumber(message.usage[field])) clean[field] = message.usage[field];
+      }
+      if (validNumber(message.usage.output_tokens_details?.reasoning_tokens)) clean.output_tokens_details = { reasoning_tokens: message.usage.output_tokens_details.reasoning_tokens };
+      const previous = messages.get(key);
+      // Stream fragments can have growing output counts. Preserve the maximal count for a single request.
+      if (previous) {
+        for (const field of ['input_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens']) {
+          if (previous[field] !== undefined && clean[field] !== undefined && previous[field] !== clean[field]) warnings.push('Conflicting Claude input usage for the same request/message.');
+        }
+        for (const field of ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens']) {
+          if (previous[field] !== undefined) clean[field] = Math.max(previous[field], clean[field] ?? 0);
+        }
+        clean.output_tokens_details ??= previous.output_tokens_details;
+      }
+      clean.selected = selected || previous?.selected || false;
+      clean.outside = !selected || previous?.outside || false;
+      messages.set(key, clean);
+    }
+    for (const [key, u] of messages) {
+      if (!u.selected) continue;
+      if (u.outside) { warnings.push('Claude request spans a time boundary; ambiguous request omitted.'); continue; }
+      accumulate(normalizeClaude(u));
+      requestKeys.push(hash(key));
+      for (const [k, v] of Object.entries(u)) if (validNumber(v)) raw[k] = (raw[k] ?? 0) + v;
+    }
+  }
+  if (options.sessionId && !ids.has(options.sessionId)) throw new Error('Native session ID does not match the selected log');
+  if (options.agentId && !agents.has(options.agentId)) throw new Error('Native agent ID does not match the selected log');
+  if (ids.size > 1) warnings.push('Multiple native session IDs in source; attribution requires explicit review.');
+  if (!observed) warnings.push('No attributable usage records. Missing values are not zero.');
+  if (usage.input === null || usage.output === null || usage.total === null) warnings.push('Core token counts unavailable or incomplete.');
+  const sorted = times.map(Date.parse).filter(Number.isFinite).sort((a, b) => a - b);
+  return { schemaVersion: 1, provider, sourceHash: hash(text), sessionIds: [...ids], agentIds: [...agents],
+    models: [...models], versions: [...versions], efforts: [...efforts], usage, nativeUsage: raw,
+    usageRecords: observed, requestKeys, warnings: [...new Set(warnings)],
+    observedDurationMs: sorted.length > 1 ? sorted.at(-1) - sorted[0] : null,
+    skillInvocations: skillInvocations.filter((entry, index, all) => index === all.findIndex(other => other.skill === entry.skill && other.timestamp === entry.timestamp)),
+    commandInvocations: commandInvocations.filter((entry, index, all) => index === all.findIndex(other => other.command === entry.command && other.timestamp === entry.timestamp)),
+    from: options.from ?? null, to: options.to ?? null };
+}
+export const importUsage = (file, provider, options) => parseUsage(fs.readFileSync(file, 'utf8'), provider, options);