pacework 1.2.0 → 1.4.1

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.
package/lib/skills.mjs ADDED
@@ -0,0 +1,130 @@
1
+ /**
2
+ * Agent skills for a run (PWK-145).
3
+ *
4
+ * The run carries the agent's skills in the SKILL.md format. They are written
5
+ * where the coding tools look for skills in a project, so the tool reads each
6
+ * skill's name and description and loads the full instructions only when a task
7
+ * needs them:
8
+ *
9
+ * .claude/skills/<slug>/ Claude Code
10
+ * .agents/skills/<slug>/ Codex and others following the same layout
11
+ *
12
+ * The files are kept out of git (the checkout's info/exclude), so they never
13
+ * reach a commit or the runner's changed-file count, and are removed after the
14
+ * run. A skill the repository already ships under the same name is left alone:
15
+ * the repository's own version wins.
16
+ */
17
+
18
+ import fs from "node:fs"
19
+ import path from "node:path"
20
+ import { execFileSync } from "node:child_process"
21
+
22
+ export const SKILL_DIRS = [".claude/skills", ".agents/skills"]
23
+ const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/
24
+ const EXCLUDE_MARK = "# pacework run skills"
25
+
26
+ function skillMarkdown(skill) {
27
+ const description = String(skill.description ?? "").replace(/\s+/g, " ").trim()
28
+ return `---\nname: ${skill.slug}\ndescription: ${JSON.stringify(description)}\n---\n\n${String(skill.instructions ?? "").trim()}\n`
29
+ }
30
+
31
+ /** A supporting file's path, if it stays inside the skill folder. */
32
+ function safeRelative(file) {
33
+ const normalized = String(file).replace(/\\/g, "/").replace(/^\.\//, "")
34
+ if (!normalized || normalized.startsWith("/") || normalized.split("/").some((part) => part === ".." || part === "")) return null
35
+ if (normalized.toLowerCase() === "skill.md") return null
36
+ return normalized
37
+ }
38
+
39
+ function gitExcludePath(checkout) {
40
+ try {
41
+ const relative = execFileSync("git", ["-C", checkout, "rev-parse", "--git-path", "info/exclude"], { encoding: "utf8" }).trim()
42
+ return path.isAbsolute(relative) ? relative : path.join(checkout, relative)
43
+ } catch {
44
+ return null
45
+ }
46
+ }
47
+
48
+ /**
49
+ * Write the run's skills into the checkout. Returns what was installed and
50
+ * skipped, and a cleanup() that removes the installed files again.
51
+ */
52
+ export function installSkills(checkout, skills, { log = () => {} } = {}) {
53
+ const installed = []
54
+ const skipped = []
55
+ const created = []
56
+ for (const skill of Array.isArray(skills) ? skills : []) {
57
+ if (!skill || !SLUG.test(String(skill.slug ?? ""))) {
58
+ skipped.push({ slug: String(skill?.slug ?? ""), reason: "invalid name" })
59
+ continue
60
+ }
61
+ const targets = SKILL_DIRS.map((dir) => path.join(checkout, dir, skill.slug))
62
+ if (targets.some((target) => fs.existsSync(target))) {
63
+ skipped.push({ slug: skill.slug, reason: "the repository has its own skill with this name" })
64
+ continue
65
+ }
66
+ for (const target of targets) {
67
+ fs.mkdirSync(target, { recursive: true })
68
+ created.push(target)
69
+ fs.writeFileSync(path.join(target, "SKILL.md"), skillMarkdown(skill))
70
+ for (const [file, content] of Object.entries(skill.files ?? {})) {
71
+ const relative = safeRelative(file)
72
+ if (!relative || typeof content !== "string") continue
73
+ fs.mkdirSync(path.dirname(path.join(target, relative)), { recursive: true })
74
+ fs.writeFileSync(path.join(target, relative), content)
75
+ }
76
+ }
77
+ installed.push(skill.slug)
78
+ }
79
+
80
+ // Keep them out of git: never committed, never counted as changed files.
81
+ const excludeFile = installed.length ? gitExcludePath(checkout) : null
82
+ let excludeAdded = null
83
+ if (excludeFile) {
84
+ const lines = installed.flatMap((slug) => SKILL_DIRS.map((dir) => `/${dir}/${slug}/`))
85
+ excludeAdded = `${EXCLUDE_MARK}\n${lines.join("\n")}\n${EXCLUDE_MARK} end\n`
86
+ fs.mkdirSync(path.dirname(excludeFile), { recursive: true })
87
+ const current = fs.existsSync(excludeFile) ? fs.readFileSync(excludeFile, "utf8") : ""
88
+ fs.writeFileSync(excludeFile, `${current}${current && !current.endsWith("\n") ? "\n" : ""}${excludeAdded}`)
89
+ }
90
+ if (installed.length) log(`Installed ${installed.length} skill(s): ${installed.join(", ")}`)
91
+ for (const skip of skipped) log(`Skipped skill ${skip.slug || "(unnamed)"}: ${skip.reason}`)
92
+
93
+ return {
94
+ installed,
95
+ skipped,
96
+ cleanup() {
97
+ for (const target of created) fs.rmSync(target, { recursive: true, force: true })
98
+ // Remove the skill folders we created only if nothing else is in them.
99
+ for (const dir of SKILL_DIRS) {
100
+ for (const folder of [path.join(checkout, dir), path.dirname(path.join(checkout, dir))]) {
101
+ try { if (fs.readdirSync(folder).length === 0) fs.rmdirSync(folder) } catch { /* absent or not empty */ }
102
+ }
103
+ }
104
+ if (excludeFile && excludeAdded && fs.existsSync(excludeFile)) {
105
+ fs.writeFileSync(excludeFile, fs.readFileSync(excludeFile, "utf8").replace(excludeAdded, ""))
106
+ }
107
+ },
108
+ }
109
+ }
110
+
111
+ /** The skills section of the agent's prompt; empty when there are none. */
112
+ export function skillsPromptSection(skills) {
113
+ const list = (Array.isArray(skills) ? skills : []).filter((skill) => SLUG.test(String(skill?.slug ?? "")))
114
+ if (!list.length) return ""
115
+ return [
116
+ "Skills: this checkout has skills for you in .claude/skills and .agents/skills (one folder each, SKILL.md inside).",
117
+ "Read a skill's SKILL.md when its description fits the task, and follow it:",
118
+ ...list.map((skill) => `- ${skill.slug}: ${String(skill.description ?? "").replace(/\s+/g, " ").trim()}`),
119
+ "These files are not part of the repository; do not commit or edit them.",
120
+ "At the very end of your final report, add one line: `Skills used: <names, comma-separated>` (or `Skills used: none`).",
121
+ ].join("\n")
122
+ }
123
+
124
+ /** The skills the agent says it used, limited to the skills it was given. */
125
+ export function parseSkillsUsed(report, offered) {
126
+ const known = new Set((offered ?? []).map(String))
127
+ const match = String(report ?? "").match(/skills used\s*:\s*(.+)$/im)
128
+ if (!match) return []
129
+ return [...new Set(match[1].replace(/[`*.]/g, "").split(/[,;]\s*|\s+and\s+/).map((name) => name.trim().toLowerCase()).filter((name) => known.has(name)))]
130
+ }
@@ -79,7 +79,12 @@ function runExecutorPrompt(options, prompt) {
79
79
  /**
80
80
  * Polls until `shouldStop()` returns true (or after one job with `once`).
81
81
  * `report(event, details)` receives: started, claimed, completed, failed,
82
- * rejected, poll_error and auth_failed; callers turn those into log lines.
82
+ * rejected, poll_error, auth_failed and auth_recovered; callers turn those
83
+ * into log lines.
84
+ *
85
+ * A rejected key does not end the loop. It used to: triage stopped for good
86
+ * while the runner stayed online, so requests went untriaged with nothing
87
+ * looking wrong (PWK-113). Polling slows to `authRetryMs` until the key works.
83
88
  */
84
89
  export async function runTriageLoop({
85
90
  appUrl,
@@ -88,6 +93,7 @@ export async function runTriageLoop({
88
93
  model = null,
89
94
  runnerName = `${os.hostname()} triage`,
90
95
  pollIntervalMs = 5000,
96
+ authRetryMs = 5 * 60_000,
91
97
  timeoutMs = 240_000,
92
98
  binaries = {},
93
99
  once = false,
@@ -132,12 +138,23 @@ export async function runTriageLoop({
132
138
  }
133
139
 
134
140
  report("started", { runnerName, executor, model, pollIntervalMs })
141
+ /** Set while the server rejects the key; reported once per streak. */
142
+ let authFailedSince = null
135
143
  while (!shouldStop()) {
136
144
  try {
137
145
  const claim = await api("/api/triage-runner/claim", { runner_name: runnerName })
138
146
  if (claim.status === 401 || claim.status === 403) {
139
- report("auth_failed", { status: claim.status })
140
- return
147
+ if (authFailedSince === null) {
148
+ authFailedSince = Date.now()
149
+ report("auth_failed", { status: claim.status, retryMs: authRetryMs })
150
+ }
151
+ if (once) return
152
+ await sleep(authRetryMs, shouldStop)
153
+ continue
154
+ }
155
+ if (authFailedSince !== null) {
156
+ report("auth_recovered", { downMs: Date.now() - authFailedSince })
157
+ authFailedSince = null
141
158
  }
142
159
  if (claim.status >= 400) {
143
160
  report("poll_error", { message: `claim failed (${claim.status}): ${JSON.stringify(claim.payload)}` })
@@ -150,6 +167,14 @@ export async function runTriageLoop({
150
167
  report("poll_error", { message: error instanceof Error ? error.message : String(error) })
151
168
  }
152
169
  if (once) return
153
- await new Promise((resolve) => setTimeout(resolve, pollIntervalMs))
170
+ await sleep(pollIntervalMs, shouldStop)
171
+ }
172
+ }
173
+
174
+ /** Waits up to `ms`, waking early once `shouldStop()` turns true. */
175
+ async function sleep(ms, shouldStop) {
176
+ const until = Date.now() + ms
177
+ while (Date.now() < until && !shouldStop()) {
178
+ await new Promise((resolve) => setTimeout(resolve, Math.min(1000, until - Date.now())))
154
179
  }
155
180
  }
@@ -10,6 +10,13 @@
10
10
  // out: an agent working on rate limiting says it all the time.
11
11
  const LIMIT_PATTERN = /usage limit|hit your (?:usage )?limit|limit reached|quota exceeded|insufficient_quota|credit balance is too low|\b429\b[^\n]{0,40}rate.?limit|rate.?limit[^\n]{0,40}\b429\b/i
12
12
 
13
+ /**
14
+ * How a run stopped by a usage limit starts its error message. The server
15
+ * treats a failure as a usage limit only when it starts with this, so keep it
16
+ * in step with USAGE_LIMIT_MARKER in backend control-plane/runner-usage-limit.ts.
17
+ */
18
+ export const USAGE_LIMIT_MARKER = "Usage limit reached on "
19
+
13
20
  /** When the limit is not stated, wait this long before trying again. */
14
21
  export const DEFAULT_LIMIT_WAIT_MS = 30 * 60_000
15
22
 
@@ -29,6 +36,22 @@ export function detectUsageLimit(text, now = new Date()) {
29
36
  : { resetAt: new Date(now.getTime() + DEFAULT_LIMIT_WAIT_MS), stated: false }
30
37
  }
31
38
 
39
+ /**
40
+ * The usage limit that stopped a failed run, or null.
41
+ *
42
+ * Only the AI tool can hit a usage limit, so only a failure while it was
43
+ * running is looked at. A failure after it finished (the tripwire, a commit, a
44
+ * push or pull request on GitHub) is never one, whatever the tool's final
45
+ * words or the git error happen to say.
46
+ *
47
+ * @param {{ phase: "before" | "running" | "finished", canceled?: boolean, text: string }} failure
48
+ * `phase` is where the run was when it failed, relative to the AI tool.
49
+ */
50
+ export function detectRunUsageLimit({ phase, canceled = false, text }, now = new Date()) {
51
+ if (canceled || phase !== "running") return null
52
+ return detectUsageLimit(text, now)
53
+ }
54
+
32
55
  function parseResetTime(text, now) {
33
56
  // Claude Code: "Claude AI usage limit reached|1761058800" (epoch seconds).
34
57
  const epoch = text.match(/limit reached\|(\d{10})\b/i)
@@ -0,0 +1,27 @@
1
+ /**
2
+ * The CLI's own npm package. The update check and `pacework update` both use
3
+ * this name: they used to ask for "pacework-runner", a name nobody owns, so no
4
+ * one was told about updates and `pacework update` would have installed
5
+ * whatever someone published under that name.
6
+ */
7
+ export const NPM_PACKAGE = "pacework"
8
+
9
+ /** True when version a is newer than b (plain x.y.z; anything else counts as not newer). */
10
+ export function isNewerVersion(a, b) {
11
+ const parse = (value) => /^\d+\.\d+\.\d+$/.test(String(value)) ? String(value).split(".").map(Number) : null
12
+ const left = parse(a)
13
+ const right = parse(b)
14
+ if (!left || !right) return false
15
+ for (let index = 0; index < 3; index++) {
16
+ if (left[index] !== right[index]) return left[index] > right[index]
17
+ }
18
+ return false
19
+ }
20
+
21
+ /** The latest published version, or null when the registry cannot be reached. */
22
+ export async function latestPublishedVersion(fetchImpl = fetch) {
23
+ const res = await fetchImpl(`https://registry.npmjs.org/${NPM_PACKAGE}/latest`, { signal: AbortSignal.timeout(4000) })
24
+ if (!res.ok) return null
25
+ const { version } = await res.json()
26
+ return typeof version === "string" ? version : null
27
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pacework",
3
- "version": "1.2.0",
3
+ "version": "1.4.1",
4
4
  "description": "pacework CLI: connect this machine as a runner for pacework AI agents",
5
5
  "type": "module",
6
6
  "bin": {