robisie 0.1.0 → 0.1.2

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.
Files changed (87) hide show
  1. package/CHANGELOG.md +79 -0
  2. package/README.md +109 -14
  3. package/dist/active-recovery.d.ts +58 -0
  4. package/dist/active-recovery.js +143 -0
  5. package/dist/agents.d.ts +34 -0
  6. package/dist/agents.js +77 -16
  7. package/dist/attempt-identity.d.ts +21 -0
  8. package/dist/attempt-identity.js +39 -0
  9. package/dist/ci-failure-result.d.ts +23 -0
  10. package/dist/ci-failure-result.js +90 -0
  11. package/dist/claude-headless.d.ts +7 -0
  12. package/dist/claude-headless.js +28 -0
  13. package/dist/cli.d.ts +17 -0
  14. package/dist/cli.js +54 -14
  15. package/dist/commands.d.ts +18 -0
  16. package/dist/commands.js +195 -88
  17. package/dist/constants.d.ts +32 -0
  18. package/dist/constants.js +3 -3
  19. package/dist/context.d.ts +24 -0
  20. package/dist/context.js +22 -6
  21. package/dist/dependency-readiness.d.ts +13 -0
  22. package/dist/dependency-readiness.js +80 -0
  23. package/dist/dispatch-scope.d.ts +18 -0
  24. package/dist/dispatch-scope.js +46 -0
  25. package/dist/done-evidence.d.ts +31 -0
  26. package/dist/done-evidence.js +216 -0
  27. package/dist/engine-config.d.ts +65 -0
  28. package/dist/engine-config.js +139 -0
  29. package/dist/fsops.d.ts +87 -0
  30. package/dist/fsops.js +117 -24
  31. package/dist/helpers.d.ts +15 -0
  32. package/dist/helpers.js +268 -45
  33. package/dist/intent-rules/admission.d.ts +10 -0
  34. package/dist/intent-rules/admission.js +35 -0
  35. package/dist/intent-rules/done-when-roles.d.ts +21 -0
  36. package/dist/intent-rules/done-when-roles.js +101 -0
  37. package/dist/intent-rules/hooks.d.ts +29 -0
  38. package/dist/intent-rules/hooks.js +23 -0
  39. package/dist/k3-codex-role.d.ts +20 -0
  40. package/dist/k3-codex-role.js +68 -0
  41. package/dist/manifest.d.ts +41 -0
  42. package/dist/manifest.js +59 -14
  43. package/dist/mcp.d.ts +18 -0
  44. package/dist/mcp.js +117 -40
  45. package/dist/opencode-result.d.ts +19 -0
  46. package/dist/opencode-result.js +136 -0
  47. package/dist/opencode-review-guard.d.ts +1 -0
  48. package/dist/opencode-review-guard.js +19 -0
  49. package/dist/opencode-session-export.d.ts +5 -0
  50. package/dist/opencode-session-export.js +28 -0
  51. package/dist/outcome-moves.d.ts +15 -0
  52. package/dist/outcome-moves.js +39 -0
  53. package/dist/planer-client.d.ts +214 -0
  54. package/dist/planer-client.js +351 -0
  55. package/dist/restart-recovery.d.ts +47 -0
  56. package/dist/restart-recovery.js +70 -0
  57. package/dist/review-source-packet.d.ts +17 -0
  58. package/dist/review-source-packet.js +44 -0
  59. package/dist/role-registry.d.ts +25 -0
  60. package/dist/role-registry.js +91 -0
  61. package/dist/role-results.d.ts +15 -0
  62. package/dist/role-results.js +42 -0
  63. package/dist/roles.d.ts +30 -0
  64. package/dist/roles.js +20 -16
  65. package/dist/seed-validation.d.ts +28 -0
  66. package/dist/seed-validation.js +294 -0
  67. package/dist/selection-result.d.ts +44 -0
  68. package/dist/selection-result.js +144 -0
  69. package/dist/sparse-policy.d.ts +8 -0
  70. package/dist/sparse-policy.js +49 -0
  71. package/dist/tester-identity.d.ts +11 -0
  72. package/dist/tester-identity.js +53 -0
  73. package/dist/worker-env.d.ts +5 -0
  74. package/dist/worker-env.js +34 -0
  75. package/docs/ENGINE-API.md +88 -0
  76. package/docs/ENGINE-CONFIG.md +113 -0
  77. package/docs/README.en.md +142 -20
  78. package/docs/README.md +144 -20
  79. package/docs/RELEASE-0.1.0.md +81 -8
  80. package/docs/RELEASE-0.1.1.md +110 -0
  81. package/helpers/ceo-client-launcher-mcp.mjs +36 -8
  82. package/helpers/client-spawn-session.sh +181 -0
  83. package/helpers/client-spawn.sh +825 -0
  84. package/package.json +9 -4
  85. package/roles/ceo-client.md +3 -2
  86. package/roles/manager-builder-client.md +18 -4
  87. package/roles/quality-officer-client.md +20 -6
@@ -1,8 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  import { execFile } from "node:child_process";
4
- import { accessSync, constants, lstatSync, realpathSync } from "node:fs";
5
- import { resolve } from "node:path";
4
+ import { accessSync, constants, lstatSync, readFileSync, realpathSync } from "node:fs";
5
+ import { join, resolve } from "node:path";
6
6
  import { promisify } from "node:util";
7
7
  import { fileURLToPath } from "node:url";
8
8
 
@@ -16,6 +16,7 @@ import { verifyReviewReceipt } from "./lib/client-review-receipt.mjs";
16
16
  import { createSpawnFailureRecord } from "./lib/client-spawn-failure.mjs";
17
17
 
18
18
  const execFileAsync = promisify(execFile);
19
+ const CLIENT_SPAWN_PATH = fileURLToPath(new URL("./client-spawn.sh", import.meta.url));
19
20
  const UUID_PATTERN = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/;
20
21
  const HISTORY_KEY_PATTERN =
21
22
  /^quality_review_[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/u;
@@ -23,12 +24,12 @@ const SHA_PATTERN = /^[0-9a-f]{64}$/u;
23
24
  const PLANER_ENDPOINT = new URL("https://robisie.app/api/mcp");
24
25
  const MCP_CALL_TIMEOUT_MS = 30_000;
25
26
  const MCP_CLOSE_TIMEOUT_MS = 5_000;
26
- const AGENT_COMMAND =
27
- "claude --print --agent manager-builder-client --permission-mode dontAsk 'Start the assigned client task now. Read launch context first and follow the role contract through review handoff.'";
27
+ const BUILDER_PROMPT = "Start the assigned client task now. Read launch context first and follow the role contract through review handoff.";
28
28
  const RESERVATION_TIMEOUT_MS = 30_000;
29
29
  const RESERVATION_POLL_MS = 500;
30
30
  const BASE_ENV_NAMES = [
31
31
  "HOME",
32
+ "CODEX_HOME",
32
33
  "LANG",
33
34
  "LC_ALL",
34
35
  "LC_CTYPE",
@@ -40,6 +41,7 @@ const BASE_ENV_NAMES = [
40
41
  "TMPDIR",
41
42
  "USER",
42
43
  "XDG_DATA_DIRS",
44
+ "XDG_CONFIG_HOME",
43
45
  ];
44
46
  const LAUNCH_ENV_NAMES = [
45
47
  ...BASE_ENV_NAMES,
@@ -91,6 +93,32 @@ export function validateLauncherResult(value, cardRef) {
91
93
  return result;
92
94
  }
93
95
 
96
+ function builderCommand(environment) {
97
+ let configDir;
98
+ let provider;
99
+ try {
100
+ if (!environment.XDG_CONFIG_HOME && !environment.HOME) {
101
+ throw new Error("configuration directory is missing");
102
+ }
103
+ configDir = join(environment.XDG_CONFIG_HOME || join(environment.HOME, ".config"), "robisie");
104
+ const manifest = JSON.parse(readFileSync(join(configDir, "manifest.json"), "utf8"));
105
+ // Match init's migration of legacy single-provider installs; never guess an ambiguous assignment.
106
+ provider = Object.hasOwn(manifest, "roleProviders")
107
+ ? manifest.roleProviders?.builder
108
+ : Array.isArray(manifest.agents) && manifest.agents.length === 1 ? manifest.agents[0] : undefined;
109
+ } catch {
110
+ throw new Error("Builder configuration could not be read; run npx robisie init");
111
+ }
112
+ if (!["claude", "codex", "opencode"].includes(provider)) {
113
+ throw new Error("Builder provider is missing or invalid; configure builder with npx robisie init --role");
114
+ }
115
+ if (provider === "claude") return `claude --print --agent manager-builder-client --permission-mode dontAsk '${BUILDER_PROMPT}'`;
116
+ if (provider === "opencode") return `opencode run --agent manager-builder-client '${BUILDER_PROMPT}'`;
117
+ const rolePath = join(configDir, "roles", "codex", "manager-builder-client.md");
118
+ const prompt = `Act as the robisie Builder: read ${rolePath} in full and follow it. ${BUILDER_PROMPT}`;
119
+ return `codex exec '${prompt.replace(/'/g, "'\\''")}'`;
120
+ }
121
+
94
122
  export function buildLaunchContract(cardRef, projectContext, sourceEnvironment) {
95
123
  const validatedCardRef = validateCardRef(cardRef);
96
124
  if (
@@ -101,12 +129,12 @@ export function buildLaunchContract(cardRef, projectContext, sourceEnvironment)
101
129
  throw new Error("project context must be one absolute directory path");
102
130
  }
103
131
  return {
104
- file: resolve(projectContext, "scripts/client-spawn.sh"),
132
+ file: CLIENT_SPAWN_PATH,
105
133
  args: [validatedCardRef],
106
134
  cwd: projectContext,
107
135
  env: {
108
136
  ...copyLaunchEnvironment(sourceEnvironment),
109
- ROBISIE_AGENT_COMMAND: AGENT_COMMAND,
137
+ ROBISIE_AGENT_COMMAND: builderCommand(sourceEnvironment),
110
138
  ROBISIE_PROJECT_CONTEXT: projectContext,
111
139
  },
112
140
  };
@@ -380,10 +408,10 @@ function validateRuntimeContract(contract) {
380
408
  if (!contextStat.isDirectory() || contextStat.isSymbolicLink()) {
381
409
  throw new Error("project context must be a real directory");
382
410
  }
383
- const expectedLauncher = resolve(realpathSync(contract.cwd), "scripts/client-spawn.sh");
411
+ const expectedLauncher = realpathSync(CLIENT_SPAWN_PATH);
384
412
  const actualLauncher = realpathSync(contract.file);
385
413
  if (actualLauncher !== expectedLauncher) {
386
- throw new Error("launcher resolves outside the selected project context");
414
+ throw new Error("launcher resolves outside the helper module location");
387
415
  }
388
416
  const launcherStat = lstatSync(actualLauncher);
389
417
  if (!launcherStat.isFile() || launcherStat.isSymbolicLink()) {
@@ -0,0 +1,181 @@
1
+ #!/usr/bin/env bash
2
+ # Terminal-side lifecycle wrapper for client-spawn.sh. This file is invoked
3
+ # inside the new terminal and owns the card lock for exactly as long as the
4
+ # configured agent process remains alive.
5
+ set -euo pipefail
6
+
7
+ OWNER_PREFIX="robisie-client-spawn-v1"
8
+ STATE_DIR="${1:-}"
9
+ EXPECTED_OWNER="${2:-}"
10
+ CARD_REF="${3:-}"
11
+ STATE_ROOT=""
12
+ STATE_KEY=""
13
+ AGENT_PID=""
14
+ OWNERSHIP_VALIDATED=0
15
+ GENERATION=""
16
+ RUNNER_CLAIM=""
17
+ RUNNER_PID_FILE=""
18
+ AGENT_PID_FILE=""
19
+ READY_FILE=""
20
+ FAILED_FILE=""
21
+ TOKEN_FIFO=""
22
+
23
+ sha256_text() {
24
+ local value="$1" digest=""
25
+ if command -v sha256sum >/dev/null 2>&1; then
26
+ digest="$(printf '%s' "$value" | sha256sum)"
27
+ elif command -v shasum >/dev/null 2>&1; then
28
+ digest="$(printf '%s' "$value" | shasum -a 256)"
29
+ else
30
+ return 1
31
+ fi
32
+ digest="${digest%% *}"
33
+ [[ "$digest" =~ ^[0-9a-f]{64}$ ]] || return 1
34
+ printf '%s' "$digest"
35
+ }
36
+
37
+ state_is_owned() {
38
+ local marker=""
39
+ [[ "$OWNERSHIP_VALIDATED" -eq 1 ]] || return 1
40
+ [[ -d "$STATE_DIR" && -f "$STATE_DIR/.owner" ]] || return 1
41
+ IFS= read -r marker < "$STATE_DIR/.owner" || return 1
42
+ [[ "$marker" == "$EXPECTED_OWNER" ]]
43
+ }
44
+
45
+ write_owned_line() {
46
+ local path="$1" value="$2"
47
+ state_is_owned || return 1
48
+ printf '%s\n' "$value" > "$path"
49
+ }
50
+
51
+ fail_state() {
52
+ local message="$1"
53
+ if state_is_owned; then
54
+ write_owned_line "$FAILED_FILE" "$message" 2>/dev/null || true
55
+ fi
56
+ echo "client-spawn-session: $message" >&2
57
+ exit 4
58
+ }
59
+
60
+ read_state_line() {
61
+ local file="$1" value=""
62
+ state_is_owned || return 1
63
+ [[ -f "$file" ]] || return 1
64
+ IFS= read -r value < "$file" || [[ -n "$value" ]] || return 1
65
+ state_is_owned || return 1
66
+ printf '%s' "$value"
67
+ }
68
+
69
+ cleanup_state() {
70
+ state_is_owned || return 0
71
+ case "$STATE_DIR" in "$STATE_ROOT/$STATE_KEY.lock") ;; *) return 1 ;; esac
72
+ rm -rf -- "$STATE_DIR"
73
+ }
74
+
75
+ # Invoked indirectly by the signal traps installed below.
76
+ # shellcheck disable=SC2329
77
+ forward_signal() {
78
+ local signal="$1"
79
+ if [[ "$AGENT_PID" =~ ^[0-9]+$ ]] && kill -0 "$AGENT_PID" 2>/dev/null; then
80
+ kill -"$signal" "$AGENT_PID" 2>/dev/null || true
81
+ wait "$AGENT_PID" 2>/dev/null || true
82
+ fi
83
+ cleanup_state
84
+ exit 130
85
+ }
86
+
87
+ [[ -n "$STATE_DIR" && "$STATE_DIR" == /* && "$STATE_DIR" != *$'\n'* ]] || fail_state "absolute state directory argument is required"
88
+ [[ "$EXPECTED_OWNER" =~ ^${OWNER_PREFIX}:[[:alnum:]._-]+$ ]] || fail_state "state generation token is missing or invalid"
89
+ [[ "$CARD_REF" =~ ^[[:alnum:]][[:alnum:].:_-]{0,127}$ ]] || fail_state "card-ref argument is missing or invalid"
90
+ CARD_DIGEST="$(sha256_text "$CARD_REF")" || fail_state "sha256sum or shasum is required to verify the portable card lock"
91
+ STATE_KEY="card-$CARD_DIGEST"
92
+ STATE_ROOT="${STATE_DIR%/*}"
93
+ [[ -n "$STATE_ROOT" && "$STATE_DIR" == "$STATE_ROOT/$STATE_KEY.lock" ]] || fail_state "state path is outside the expected card lock"
94
+ GENERATION="${EXPECTED_OWNER#*:}"
95
+ RUNNER_CLAIM="$STATE_DIR/runner.claim.$GENERATION"
96
+ RUNNER_PID_FILE="$STATE_DIR/runner.$GENERATION.pid"
97
+ AGENT_PID_FILE="$STATE_DIR/agent.$GENERATION.pid"
98
+ READY_FILE="$STATE_DIR/ready.$GENERATION"
99
+ FAILED_FILE="$STATE_DIR/failed.$GENERATION"
100
+ TOKEN_FIFO="$STATE_DIR/token.$GENERATION.fifo"
101
+
102
+ OWNERSHIP_VALIDATED=1
103
+ state_is_owned || fail_state "state ownership generation mismatch"
104
+
105
+ if ! mkdir "$RUNNER_CLAIM" 2>/dev/null; then
106
+ # A terminal retry may open a second shell, but only the first wrapper may
107
+ # ever start the agent or reserve the card.
108
+ exit 0
109
+ fi
110
+ state_is_owned || exit 4
111
+ write_owned_line "$RUNNER_PID_FILE" "$$" || fail_state "cannot record runner pid"
112
+
113
+ STORED_CARD_REF="$(read_state_line "$STATE_DIR/card-ref")" || fail_state "card-ref state is missing"
114
+ [[ "$STORED_CARD_REF" == "$CARD_REF" ]] || fail_state "card-ref state does not match launch generation"
115
+ PROJECT_CONTEXT="$(read_state_line "$STATE_DIR/project-context")" || fail_state "project context state is missing"
116
+ AGENT_COMMAND="$(read_state_line "$STATE_DIR/agent-command")" || fail_state "agent command state is missing"
117
+ BOOT_GRACE_SEC="$(read_state_line "$STATE_DIR/boot-grace")" || fail_state "boot grace state is missing"
118
+ TRANSCRIPT_PATH="$(read_state_line "$STATE_DIR/transcript-path" || true)"
119
+
120
+ if [[ -p "$TOKEN_FIFO" ]]; then
121
+ state_is_owned || exit 4
122
+ FIFO_TEST_DELAY="${ROBISIE_SPAWN_TEST_FIFO_DELAY_SEC:-0}"
123
+ [[ "$FIFO_TEST_DELAY" =~ ^[0-9]+([.][0-9]+)?$ ]] || fail_state "invalid test FIFO delay"
124
+ sleep "$FIFO_TEST_DELAY"
125
+ ROBISIE_KEY=""
126
+ IFS= read -r ROBISIE_KEY < "$TOKEN_FIFO" || [[ -n "$ROBISIE_KEY" ]] || fail_state "credential FIFO closed without a value"
127
+ state_is_owned || exit 4
128
+ rm -f "$TOKEN_FIFO" || fail_state "cannot remove consumed credential FIFO"
129
+ fi
130
+
131
+ [[ -n "${ROBISIE_KEY:-}" ]] || fail_state "ROBISIE_KEY did not reach the terminal session"
132
+ [[ -d "$PROJECT_CONTEXT" ]] || fail_state "project context does not exist"
133
+ state_is_owned || exit 4
134
+
135
+ export ROBISIE_CARD_REF="$CARD_REF"
136
+ export ROBISIE_KEY
137
+ export ROBISIE_PROJECT_CONTEXT="$PROJECT_CONTEXT"
138
+ if [[ -n "$TRANSCRIPT_PATH" ]]; then
139
+ export ROBISIE_SPAWN_TRANSCRIPT="$TRANSCRIPT_PATH"
140
+ else
141
+ unset ROBISIE_SPAWN_TRANSCRIPT 2>/dev/null || true
142
+ fi
143
+
144
+ cd "$PROJECT_CONTEXT" || fail_state "cannot enter project context"
145
+ trap 'forward_signal TERM' TERM
146
+ trap 'forward_signal INT' INT
147
+ trap 'forward_signal HUP' HUP
148
+
149
+ state_is_owned || exit 4
150
+ /bin/bash -c "$AGENT_COMMAND" &
151
+ AGENT_PID=$!
152
+ write_owned_line "$AGENT_PID_FILE" "$AGENT_PID" || {
153
+ kill "$AGENT_PID" 2>/dev/null || true
154
+ fail_state "cannot record agent pid"
155
+ }
156
+
157
+ sleep "$BOOT_GRACE_SEC"
158
+ if ! state_is_owned; then
159
+ kill "$AGENT_PID" 2>/dev/null || true
160
+ wait "$AGENT_PID" 2>/dev/null || true
161
+ exit 4
162
+ fi
163
+ if ! kill -0 "$AGENT_PID" 2>/dev/null; then
164
+ set +e
165
+ wait "$AGENT_PID"
166
+ agent_rc=$?
167
+ set -e
168
+ fail_state "agent exited before readiness (rc=$agent_rc)"
169
+ fi
170
+
171
+ write_owned_line "$READY_FILE" "ready" || {
172
+ kill "$AGENT_PID" 2>/dev/null || true
173
+ fail_state "cannot publish readiness marker"
174
+ }
175
+
176
+ set +e
177
+ wait "$AGENT_PID"
178
+ agent_rc=$?
179
+ set -e
180
+ cleanup_state
181
+ exit "$agent_rc"