ultra-builder-pro-cli 3.0.2 → 5.0.0

package/skills/ultra-delegate/patches/zcode-acp-0.1.0-zcode-0.16.5.patch

@@ -0,0 +1,184 @@
+diff --git a/Cargo.lock b/Cargo.lock
+index bfadfbb..4b1d665 100644
+--- a/Cargo.lock
++++ b/Cargo.lock
+@@ -2492,7 +2492,7 @@ dependencies = [
+ 
+ [[package]]
+ name = "zcode-acp"
+-version = "0.1.0"
++version = "0.1.0+ultra.zcode.0.16.5"
+ dependencies = [
+  "aes-gcm",
+  "agent-client-protocol",
+diff --git a/Cargo.toml b/Cargo.toml
+index f096b91..4b4d985 100644
+--- a/Cargo.toml
++++ b/Cargo.toml
+@@ -1,6 +1,6 @@
+ [package]
+ name = "zcode-acp"
+-version = "0.1.0"
++version = "0.1.0+ultra.zcode.0.16.5"
+ edition = "2024"
+ description = "ACP adapter that bridges Buzz relay events to the ZCode CLI via its stdio app-server"
+ license = "Apache-2.0"
+diff --git a/src/zcode/mod.rs b/src/zcode/mod.rs
+index 7963959..14725bb 100644
+--- a/src/zcode/mod.rs
++++ b/src/zcode/mod.rs
+@@ -266,6 +266,13 @@ impl DriverState {
+                 }
+             }
+             Some(Incoming::ServerRequest { id, method, params }) => {
++                if method == methods::SESSION_REQUEST_RUNTIME_PREFERENCES {
++                    let _ = self.write_tx.send(json!({
++                        "id": id,
++                        "result": default_runtime_preferences(),
++                    }));
++                    return;
++                }
+                 // The ACP layer answers via `reply_tx`; a side task writes the
+                 // reply back through `write_tx` echoing the wire id.
+                 let (reply_tx, reply_rx) = oneshot::channel();
+@@ -373,6 +380,32 @@ impl DriverState {
+     }
+ }
+ 
++fn default_runtime_preferences() -> Value {
++    json!({
++        "nativeSearchEnhancementsEnabled": true,
++        "memoryEnabled": false,
++        "askUserQuestionAutoResolutionEnabled": true,
++        "modelContextBudgetStrategy": "preflight-v1",
++    })
++}
++
++fn bootstrap_server_request_response(id: RequestId, method: &str) -> Value {
++    if method == methods::SESSION_REQUEST_RUNTIME_PREFERENCES {
++        json!({
++            "id": id,
++            "result": default_runtime_preferences(),
++        })
++    } else {
++        json!({
++            "id": id,
++            "error": {
++                "code": -32601,
++                "message": format!("Unsupported app-server request: {method}"),
++            },
++        })
++    }
++}
++
+ /// Run the dispatcher: read framed messages, dispatch each into shared state.
+ async fn run_dispatcher(
+     state: Arc<Mutex<DriverState>>,
+@@ -647,6 +680,15 @@ pub async fn build_session(
+                     protocol::ResponseResult::Ok(v) => break v,
+                     protocol::ResponseResult::Err(e) => return Err(SessionError::CreateFailed(e)),
+                 },
++                Some(Incoming::ServerRequest {
++                    id: request_id,
++                    method,
++                    ..
++                }) => {
++                    write_tx
++                        .send(bootstrap_server_request_response(request_id, &method))
++                        .map_err(|e| SessionError::Send(e.to_string()))?;
++                }
+                 _ => continue,
+             },
+             None => return Err(SessionError::TransportClosed),
+diff --git a/src/zcode/protocol.rs b/src/zcode/protocol.rs
+index 71fa3e9..6e3e595 100644
+--- a/src/zcode/protocol.rs
++++ b/src/zcode/protocol.rs
+@@ -138,6 +138,7 @@ impl IncomingMessage {
+ 
+ pub mod methods {
+     pub const SESSION_CREATE: &str = "session/create";
++    pub const SESSION_REQUEST_RUNTIME_PREFERENCES: &str = "session/requestRuntimePreferences";
+     pub const SESSION_RESUME: &str = "session/resume";
+     pub const SESSION_LIST: &str = "session/list";
+     pub const SESSION_SUBSCRIBE: &str = "session/subscribe";
+diff --git a/tests/acp_client.py b/tests/acp_client.py
+index a407220..0e46772 100644
+--- a/tests/acp_client.py
++++ b/tests/acp_client.py
+@@ -22,6 +22,7 @@ from __future__ import annotations
+ 
+ import json
+ import os
++import select
+ import subprocess
+ import sys
+ from pathlib import Path
+@@ -40,6 +41,9 @@ def send(proc: subprocess.Popen, obj: dict) -> None:
+ 
+ def read_message(proc: subprocess.Popen) -> dict:
+     assert proc.stdout is not None
++    readable, _, _ = select.select([proc.stdout], [], [], 5)
++    if not readable:
++        raise TimeoutError("agent did not emit an ACP message within 5 seconds")
+     raw = proc.stdout.readline()
+     if not raw:
+         raise EOFError("agent closed stdout")
+@@ -74,6 +78,7 @@ def main() -> int:
+         stdin=subprocess.PIPE,
+         stdout=subprocess.PIPE,
+         stderr=sys.stderr,  # surface shim logs inline for debugging
++        bufsize=0,
+     )
+ 
+     try:
+diff --git a/tests/fake-app-server.cjs b/tests/fake-app-server.cjs
+index f6a5991..e690fbe 100644
+--- a/tests/fake-app-server.cjs
++++ b/tests/fake-app-server.cjs
+@@ -21,6 +21,8 @@ const rl = readline.createInterface({ input: process.stdin, terminal: false });
+ let sessionIdCounter = 0;
+ let activeSession = null;
+ let seqCounter = 0;
++let pendingCreateId = null;
++let runtimePreferencesRequestId = null;
+ 
+ function send(obj) {
+   process.stdout.write(JSON.stringify(obj) + "\n");
+@@ -54,10 +56,35 @@ function handle(line) {
+     return;
+   }
+   const { id, method, params } = msg;
++  if (!method && id === runtimePreferencesRequestId) {
++    const prefs = msg.result;
++    const valid = prefs
++      && prefs.nativeSearchEnhancementsEnabled === true
++      && prefs.memoryEnabled === false
++      && prefs.askUserQuestionAutoResolutionEnabled === true
++      && prefs.modelContextBudgetStrategy === "preflight-v1";
++    if (!valid) {
++      send({
++        id: pendingCreateId,
++        error: { code: -32602, message: "Invalid runtime preferences response" },
++      });
++    } else {
++      respond(pendingCreateId, { sessionId: activeSession });
++    }
++    pendingCreateId = null;
++    runtimePreferencesRequestId = null;
++    return;
++  }
+   switch (method) {
+     case "session/create": {
+       activeSession = `sess_fake_${++sessionIdCounter}`;
+-      respond(id, { sessionId: activeSession });
++      pendingCreateId = id;
++      runtimePreferencesRequestId = "server-runtime-preferences-1";
++      send({
++        id: runtimePreferencesRequestId,
++        method: "session/requestRuntimePreferences",
++        params: { sessionId: activeSession, scope: "runtime-materialization" },
++      });
+       break;
+     }
+     case "session/subscribe": {

package/skills/ultra-delegate/references/delegation-contract.md

@@ -1,5 +1,18 @@
 # Delegation artifact contract
 
+## Runtime ownership
+
+The loaded `ultra-delegate` Skill owns `scripts/delegate.cjs`,
+`scripts/delegate-worker.cjs`, `scripts/host-profile.cjs`,
+`scripts/agent-execution-driver.cjs`, `scripts/acp-driver.cjs`,
+`scripts/cli-driver.cjs`, `scripts/acp-conformance.cjs`, and its launch-only profiles.
+Invoke the launcher with the loaded Skill's absolute path. It has no package-root or
+global `ubp` dependency. The Claude and Codex profiles separately invoke exact pinned
+ACP adapter packages through `npx`; no `npx` lookup is used to locate Ultra itself.
+The package `ubp delegate` command is a thin
+one-release compatibility import of the same functions; it contains no launcher or
+worker behavior of its own.
+
 ## Permission
 
 ```json
@@ -61,7 +74,7 @@ the host prompt, extracts this object from native structured output, and adds
 failures also add `failure_type`. A nonzero process cannot publish `finished`.
 
 Every receipt, worker spec, and terminal result also records the transport truth:
-`transport_maturity` (from the shared host profile) and the exact `transport_surface`
+`transport_maturity` (from the Skill-local host profile) and the exact `transport_surface`
 wording. The ZCode headless transport is `experimental` with no public stability
 contract and is not the documented ZCode Desktop interactive surface; launching it
 requires the explicit `--ack-experimental` flag, prints a stderr warning, and stamps
@@ -69,11 +82,57 @@ requires the explicit `--ack-experimental` flag, prints a stderr warning, and st
 internal CLI run as a documented Desktop session — including failure, cancellation,
 and timeout recovery results.
 
+They also record `execution_driver`, `driver_fallback_reason`, and the probed
+`acp_capability`, including candidate-identity validity when the profile declares
+bounded local version probes. ACP results add negotiated `acp_protocol_version`, observed
+`acp_stop_reason`, and `events_file`. These are mechanical observations only. In
+particular, `stopReason: end_turn`, a completed tool call, an ACP plan, or process exit
+cannot synthesize the exact model response above or satisfy its Git-diff validation.
+
+## ACP v1 permission and event boundary
+
+The stdio client advertises no client filesystem, terminal, or terminal-auth
+capability. It creates one fresh session with the isolated worktree as absolute `cwd`,
+an empty MCP-server list, and one digest-bound text prompt. Agent-side file tools remain
+inside the Host process and the existing worktree/diff enforcement remains final.
+
+ACP `session/request_permission` uses least authority:
+
+- read, search, and think may select an offered `allow_once`;
+- edit, delete, and move may select `allow_once` only when every non-empty absolute
+  location is already inside a granted real writable root and outside `.ultra/`;
+- execute, fetch, mode switching, unknown operations, read-only writes, symlink escape,
+  and every other widening select an offered rejection and make the run terminally
+  denied;
+- `allow_always` is never selected; cancellation answers any pending permission request
+  with ACP's `cancelled` outcome.
+
+An agent may send creation-time `available_commands_update`, `current_mode_update`,
+`config_option_update`, or `session_info_update` before the `session/new` response.
+Ultra holds at most 32 such messages and 256 KiB transiently, persists no raw payload,
+and replays them only after every message session ID equals the returned session ID.
+Any other early update kind, identity mismatch, count overflow, or byte overflow is a
+typed failure; pre-session buffering cannot contribute model result text.
+
+`events.jsonl` is bounded disposable telemetry. It stores phase/update type, tool kind
+and status, counts, permission decision/scope, and terminal stop reason. It drops
+`agent_thought_chunk` entirely and never stores message text, titles, raw tool
+input/output, credentials, or protocol wire payloads. Status re-projects the latest
+record through the same fixed safe shape, so a malformed or replaced journal becomes
+`event_journal_malformed` instead of being echoed. Loss of the journal does not affect
+recovery or completion.
+
 ## Recovery
 
 - `status` distinguishes running, cancelling, stalled, and terminal artifacts.
+- ACP status may also expose the latest redacted derived event; it remains non-authoritative.
 - `cancel` writes `cancel.request`; the worker terminates its host process, publishes a
   failed result with `failure_type: cancelled`, and removes `run.lock`.
 - `--timeout` does the same with `failure_type: timeout`.
+- `ULTRA_DELEGATE_FORCE_CLI=1` bypasses ACP selection for one operator-controlled run
+  and records `acp_forced_cli`; it does not mutate the conformance record.
+- `acp_auth_required` reported by `session/new` before any prompt was sent runs the
+  immutable bounded CLI fallback once and records `acp_fallback.prompt_sent: false`.
+  No other ACP failure is retried, preventing duplicate provider work.
 - A stopped worker with no result is recoverable through `cancel`, which finalizes the
   stale run. Retry under a new delegation id and fresh digests.

package/skills/ultra-delegate/scripts/acp-conformance.cjs

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { run: runDelegate } = require('./delegate.cjs');
+const { hostProfile, ZCODE_ACP_SOURCE } = require('./host-profile.cjs');
+
+const HOSTS = new Set(['claude', 'codex', 'opencode', 'kimi', 'grok', 'zcode']);
+const RECEIPT_SCHEMA = 'ultra-acp-conformance-receipt-v1';
+
+function parseArgs(argv) {
+  const allowed = new Set(['--host', '--output', '--timeout', '--command', '--args-json']);
+  const values = {};
+  for (let index = 0; index < argv.length; index += 2) {
+    const key = argv[index];
+    const value = argv[index + 1];
+    if (!allowed.has(key) || value === undefined || value === '' || values[key] !== undefined) {
+      throw new Error(`invalid ACP conformance argument: ${key || '<missing>'}`);
+    }
+    values[key] = value;
+  }
+  if (!HOSTS.has(values['--host'])) throw new Error('ACP conformance requires a supported --host');
+  if (!values['--output']) throw new Error('ACP conformance requires --output');
+  const timeoutSeconds = values['--timeout'] === undefined ? 240 : Number(values['--timeout']);
+  if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > 600) {
+    throw new Error('ACP conformance --timeout must be between 1 and 600 seconds');
+  }
+  const hasCommand = values['--command'] !== undefined;
+  const hasArgs = values['--args-json'] !== undefined;
+  if (hasCommand !== hasArgs) throw new Error('--command and --args-json must be supplied together');
+  let argsOverride = null;
+  if (hasArgs) {
+    try { argsOverride = JSON.parse(values['--args-json']); } catch {
+      throw new Error('--args-json must be a JSON string array');
+    }
+    if (!Array.isArray(argsOverride) || !argsOverride.every((item) => typeof item === 'string')) {
+      throw new Error('--args-json must be a JSON string array');
+    }
+  }
+  return {
+    host: values['--host'],
+    output: path.resolve(values['--output']),
+    timeoutSeconds,
+    commandOverride: values['--command'] || null,
+    argsOverride,
+  };
+}
+
+function git(cwd, args) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    maxBuffer: 8 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+function sha256(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function artifactDigest(file) {
+  const stat = fs.statSync(file);
+  return { sha256: sha256(file), bytes: stat.size };
+}
+
+function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+async function waitForFile(file, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(file) && fs.statSync(file).size > 0) return;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw new Error('ACP conformance worker did not publish a terminal result before timeout');
+}
+
+async function waitForExit(pid, timeoutMs = 5000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!processAlive(pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return !processAlive(pid);
+}
+
+function createFixture(host) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), `ubp-${host}-acp-conformance-`));
+  git(root, ['init', '-b', 'main']);
+  git(root, ['config', 'user.email', 'acp-conformance@example.invalid']);
+  git(root, ['config', 'user.name', 'Ultra ACP Conformance']);
+  fs.writeFileSync(path.join(root, 'README.md'), '# Ultra ACP conformance fixture\n');
+  fs.writeFileSync(path.join(root, '.gitignore'), '.ultra/.runtime/\n');
+  git(root, ['add', 'README.md', '.gitignore']);
+  git(root, ['commit', '-m', 'test: create ACP conformance fixture']);
+
+  const id = `${host}-${crypto.randomUUID()}`;
+  const delegation = path.join(root, '.ultra', '.runtime', 'delegations', id);
+  const worktree = path.join(root, '.ultra', '.runtime', 'worktrees', id);
+  fs.mkdirSync(path.dirname(worktree), { recursive: true });
+  git(root, ['worktree', 'add', '--detach', worktree, 'HEAD']);
+  fs.mkdirSync(delegation, { recursive: true });
+  const expectedResult = {
+    $schema: 'ultra-delegation-result-v1',
+    status: 'finished',
+    summary: 'ACP conformance completed.',
+    changed_files: [],
+    checks: [],
+    evidence: [],
+    questions: [],
+    residual_risks: [],
+  };
+  fs.writeFileSync(path.join(delegation, 'instruction.md'), [
+    '# ACP conformance',
+    '',
+    'Do not use tools or modify files.',
+    'Return exactly this one-line JSON object with no prose, fences, or field changes:',
+    JSON.stringify(expectedResult),
+    '',
+  ].join('\n'));
+  fs.writeFileSync(path.join(delegation, 'permission.json'), `${JSON.stringify({
+    $schema: 'ultra-delegation-permission-v1',
+    writable_roots: [],
+    external_effects: [],
+  }, null, 2)}\n`);
+  return { root, delegation, worktree };
+}
+
+function writeReceipt(output, receipt) {
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  fs.writeFileSync(output, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+}
+
+async function runConformance(options) {
+  const profile = hostProfile(options.host);
+  if (!profile.acp || profile.acp.transport !== 'stdio'
+      || !profile.acp.protocolVersions.includes(1)) {
+    throw new Error(`host ${options.host} has no stable ACP v1 stdio candidate`);
+  }
+  const command = options.commandOverride || profile.acp.command({
+    host: options.host,
+    cliCommand: profile.binary,
+    env: process.env,
+  });
+  const args = options.argsOverride || profile.acp.argv({
+    host: options.host,
+    cliCommand: profile.binary,
+    env: process.env,
+  });
+  const fixture = createFixture(options.host);
+  let receipt;
+  try {
+    const runArgs = [
+      '--to', options.host,
+      '--instruction', path.join(fixture.delegation, 'instruction.md'),
+      '--permission', path.join(fixture.delegation, 'permission.json'),
+      '--worktree', fixture.worktree,
+      '--timeout', String(options.timeoutSeconds),
+    ];
+    if (profile.transportMaturity === 'experimental') runArgs.push('--ack-experimental');
+    const started = runDelegate(runArgs, {
+      projectRoot: fixture.root,
+      chooseExecutionDriver: () => ({
+        driver: 'acp',
+        command,
+        args,
+        protocolVersion: 1,
+        fallbackReason: null,
+        acpCapability: {
+          candidate: true,
+          surface: profile.acp.surface,
+          transport: 'stdio',
+          protocol_versions: [1],
+          conformance_status: 'probe',
+          conformance_evidence: null,
+          conformance_reason: 'Live conformance probe in progress.',
+          executable_available: true,
+          candidate_valid: true,
+        },
+      }),
+    });
+    const resultFile = path.join(fixture.delegation, 'result.json');
+    await waitForFile(resultFile, (options.timeoutSeconds * 1000) + 10000);
+    const terminal = JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+    const workerExitObserved = await waitForExit(started.worker_pid);
+    const changedFiles = Array.isArray(terminal.changed_files) ? terminal.changed_files : [];
+    const gitClean = git(fixture.worktree, ['status', '--porcelain=v1', '--untracked-files=all']) === '';
+    const artifactFiles = {
+      result: resultFile,
+      stdout: path.join(fixture.delegation, 'stdout.log'),
+      stderr: path.join(fixture.delegation, 'stderr.log'),
+      events: path.join(fixture.delegation, 'events.jsonl'),
+      host_output: path.join(fixture.delegation, 'host-result.json'),
+    };
+    const artifactDigests = {};
+    for (const [name, file] of Object.entries(artifactFiles)) {
+      if (fs.existsSync(file) && fs.statSync(file).isFile()) artifactDigests[name] = artifactDigest(file);
+    }
+    const events = fs.existsSync(artifactFiles.events)
+      ? fs.readFileSync(artifactFiles.events, 'utf8').trim().split('\n').filter(Boolean)
+      : [];
+    const passed = terminal.status === 'finished'
+      && terminal.$schema === 'ultra-delegation-result-v1'
+      && terminal.execution_driver === 'acp'
+      && terminal.acp_protocol_version === 1
+      && terminal.acp_stop_reason === 'end_turn'
+      && changedFiles.length === 0
+      && gitClean
+      && workerExitObserved;
+    receipt = {
+      $schema: RECEIPT_SCHEMA,
+      host: options.host,
+      candidate: {
+        surface: profile.acp.surface,
+        command,
+        args,
+        protocol_versions: [1],
+        override_used: options.commandOverride !== null,
+        ...(options.host === 'zcode' ? {
+          bridge_source: ZCODE_ACP_SOURCE,
+          installed_runtime: profile.binary,
+        } : {}),
+      },
+      result: {
+        status: passed ? 'passed' : 'failed',
+        execution_driver: terminal.execution_driver || null,
+        protocol_version: terminal.acp_protocol_version ?? null,
+        stop_reason: terminal.acp_stop_reason ?? null,
+        adapter_exit_code: terminal.acp_adapter_exit_code ?? null,
+        adapter_exit_signal: terminal.acp_adapter_exit_signal ?? null,
+        git_clean: gitClean,
+        changed_files_count: changedFiles.length,
+        event_count: events.length,
+        worker_exit_observed: workerExitObserved,
+        failure_type: terminal.failure_type || null,
+        validation_diagnostic: terminal.failure_type === 'invalid_result'
+          ? terminal.summary
+          : null,
+        transport_diagnostic: typeof terminal.failure_type === 'string'
+          && terminal.failure_type.startsWith('acp_')
+          ? terminal.summary
+          : null,
+      },
+      artifact_digests: artifactDigests,
+      redaction: {
+        provider_content_retained: false,
+        prompt_retained: false,
+        hidden_reasoning_retained: false,
+        credentials_retained: false,
+        temporary_artifacts_removed: true,
+      },
+      observed_at: new Date().toISOString(),
+    };
+    writeReceipt(options.output, receipt);
+    if (!passed) throw new Error(`ACP conformance failed for ${options.host}: ${terminal.failure_type || 'terminal_mismatch'}`);
+    return receipt;
+  } finally {
+    fs.rmSync(fixture.root, { recursive: true, force: true });
+  }
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  const receipt = await runConformance(options);
+  process.stdout.write(`${JSON.stringify({
+    host: receipt.host,
+    status: receipt.result.status,
+    receipt: options.output,
+  })}\n`);
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { parseArgs, runConformance };