@topolo/cli 0.13.19 → 0.13.21

package/agent-packs/src/topolo_agent_pack/work_wait.py

@@ -0,0 +1,151 @@
+"""Bounded read-only native task following; no dispatcher, retry or model turn."""
+import json
+import os
+import socket
+import stat
+import time
+import uuid
+
+from .storage import PackError, canonical, read_json
+from .work import TERMINAL, require
+
+LIMIT = 1024 * 1024
+
+
+def _remaining(deadline):
+    remaining = deadline - time.monotonic()
+    if remaining <= 0:
+        raise TimeoutError('Task wait deadline reached')
+    return remaining
+
+
+def _record(lib):
+    path = lib.root / 'live-bridge.json'
+    info = path.lstat()
+    require(stat.S_ISREG(info.st_mode) and info.st_uid == os.getuid()
+            and not info.st_mode & 0o077 and not path.is_symlink(),
+            'Task wait requires the privately owned native connection')
+    value = read_json(path)
+    require(isinstance(value, dict) and isinstance(value.get('token'), str) and value['token']
+            and isinstance(value.get('socket'), str) and os.path.isabs(value['socket']),
+            'Task wait native connection is unavailable')
+    info = os.lstat(value['socket'])
+    require(stat.S_ISSOCK(info.st_mode) and info.st_uid == os.getuid()
+            and not info.st_mode & 0o077, 'Task wait native socket ownership differs')
+    return value
+
+
+class _Connection:
+    def __init__(self, lib, record, operation, params, deadline):
+        require(_record(lib) == record, 'Native owner changed during task wait; reconnect explicitly')
+        self.socket = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self.buffer = b''
+        try:
+            self.socket.settimeout(_remaining(deadline))
+            self.socket.connect(record['socket'])
+            self.socket.settimeout(_remaining(deadline))
+            self.socket.sendall(canonical({'token': record['token'], 'operation': operation, 'params': params}) + b'\n')
+        except BaseException:
+            self.socket.close()
+            raise
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_args):
+        self.socket.close()
+
+    def read(self, deadline):
+        while b'\n' not in self.buffer:
+            require(len(self.buffer) <= LIMIT, 'Task wait response exceeds its boundary')
+            self.socket.settimeout(_remaining(deadline))
+            chunk = self.socket.recv(min(65536, LIMIT + 1 - len(self.buffer)))
+            require(chunk, 'Native task connection closed before its reply')
+            self.buffer += chunk
+        line, self.buffer = self.buffer.split(b'\n', 1)
+        require(len(line) <= LIMIT, 'Task wait response exceeds its boundary')
+        value = json.loads(line)
+        require(isinstance(value, dict), 'Native task reply is not an object')
+        require('error' not in value, 'Native task read refused: ' + str(value.get('error')))
+        return value
+
+
+def _snapshot(lib, record, task_id, deadline):
+    with _Connection(lib, record, 'work-read', {'taskId': task_id}, deadline) as connection:
+        value = connection.read(deadline)
+    require(set(value) == {'task', 'events'} and isinstance(value['task'], dict)
+            and value['task'].get('id') == task_id and isinstance(value['events'], list),
+            'Task wait readback identity differs')
+    require(type(value['task'].get('revision')) is int and value['task']['revision'] >= 1,
+            'Task wait revision is invalid')
+    events = []
+    for event in value['events']:
+        require(isinstance(event, dict), 'Task wait event is invalid')
+        if event.get('taskId') != task_id:
+            continue
+        require(type(event.get('sequence')) is int and event['sequence'] > 0,
+                'Task wait event sequence is invalid')
+        events.append(event)
+    require(len({event['sequence'] for event in events}) == len(events), 'Task event sequence repeats')
+    return {'task': value['task'], 'events': sorted(events, key=lambda event: event['sequence'])}
+
+
+def _result(task_id, snapshot, revision, sequence, timed_out):
+    if snapshot is None:
+        return {'taskId': task_id, 'task': None, 'events': [],
+                'cursor': {'revision': revision, 'sequence': sequence},
+                'changed': False, 'terminal': False, 'timedOut': True,
+                'snapshotAvailable': False, 'deliveryId': None}
+    task, events = snapshot['task'], snapshot['events']
+    current = max((event['sequence'] for event in events), default=0)
+    require(revision <= task['revision'] and sequence <= current,
+            'Task wait cursor is ahead of the canonical task')
+    return {'taskId': task_id, 'task': task,
+            'events': [event for event in events if event['sequence'] > sequence],
+            'cursor': {'revision': task['revision'], 'sequence': current},
+            'changed': task['revision'] > revision or current > sequence,
+            'terminal': task['state'] in TERMINAL, 'timedOut': timed_out,
+            'snapshotAvailable': True,
+            'deliveryId': task_id + ':' + str(task['revision']) + ':' + str(current)}
+
+
+def wait(lib, value):
+    """Follow one existing task within the caller's real native tool turn.
+
+    Repeat only on an explicit subsequent tool call with the returned cursor.
+    A timeout, native cancellation or disconnect never cancels/adopts work.
+    """
+    require(isinstance(value, dict) and set(value) == {'taskId', 'afterRevision', 'afterSequence', 'timeoutSeconds'},
+            'Exact bounded task wait request required')
+    task_id = value['taskId']
+    try:
+        valid_id = isinstance(task_id, str) and str(uuid.UUID(task_id)) == task_id
+    except ValueError:
+        valid_id = False
+    require(valid_id, 'Task wait requires the exact canonical task UUID')
+    revision, sequence, seconds = value['afterRevision'], value['afterSequence'], value['timeoutSeconds']
+    require(type(revision) is int and revision >= 0 and type(sequence) is int and sequence >= 0
+            and type(seconds) is int and 1 <= seconds <= 30, 'Task wait cursor or deadline is invalid')
+    deadline = time.monotonic() + seconds
+    record = _record(lib)
+    snapshot = None
+    try:
+        snapshot = _snapshot(lib, record, task_id, deadline)
+        result = _result(task_id, snapshot, revision, sequence, False)
+        if result['changed'] or result['terminal']:
+            return result
+        with _Connection(lib, record, 'work-watch', {}, deadline) as connection:
+            require(connection.read(deadline) == {'connected': True}, 'Native task watch was not acknowledged')
+            # Subscribe first, then re-read. A completion between the first read
+            # and watcher registration cannot disappear into a notification gap.
+            snapshot = _snapshot(lib, record, task_id, deadline)
+            while True:
+                result = _result(task_id, snapshot, revision, sequence, False)
+                if result['changed'] or result['terminal']:
+                    return result
+                event = connection.read(deadline)
+                require(set(event) == {'sequence'} and type(event['sequence']) is int and event['sequence'] >= 0,
+                        'Native task notification is invalid')
+                snapshot = _snapshot(lib, record, task_id, deadline)
+    except TimeoutError:
+        return _result(task_id, snapshot, revision, sequence, True)

package/agent-packs/templates/topolo-coordinators/AGENTS.md

@@ -0,0 +1,7 @@
+# Topolo task execution rules
+
+Load only the current specialization from Topolo Agent and the relevant canonical task and Docs/Bytes packets. This machine's conversation history is not task context. An empty workspace grants no permission to repeat, adopt or resume existing work.
+
+Preserve task, claim, owner, intent and checkpoint identities. Respect explicit holds and uncertain effects. Use supported credential-scoped Topolo actions and the governed release controller. Keep credentials out of ordinary context and evidence. Record meaningful outcomes and evidence in the existing task; distinguish reported progress, native settings acknowledgement, execution, independent verification and deployment.
+
+The three human front doors acknowledge broker receipts and remain available. Their local specialization charters define that boundary. Temporary task workers execute only their assigned phase and are archived after checkpointing; they do not become reusable lanes. Never load a whole role export, infer completion from a finished model turn, or create schedules or peer-message loops.

package/agent-packs/templates/topolo-coordinators/agents/intakes/cicd/AGENTS.md

@@ -0,0 +1,6 @@
+# Topolo CI/CD
+
+Acknowledge the queued request and remain available. If the adapter has not recorded a task, report that dispatch is unavailable; do not take over the implementation. Cloud specialization and task references must be qualified before model work.
+
+## Release-controller operating context
+The controller is the restricted internal service in Topolo-io/TopoloReleaseController, separate from the public application registry and Deploy Orchestrator. Read context/release-controller.md before routing or diagnosis: it is the selected immutable operating runbook, not task history. Current controller access, fleet endpoints and exact intent/job checkpoints belong in the selected task context. Dispatch immediate read-only diagnostics under the existing request; do not ask the human to re-explain the controller or approve an ordinary read. Use the existing broker, preserve owners and record precise missing observer access rather than guessing hosts or creating duplicate work. The submission gateway and native authority observer expose different read operations; follow the bound runbook. Mutations retain their existing release, review and effect gates.

package/agent-packs/templates/topolo-coordinators/agents/intakes/cicd/config.json

@@ -0,0 +1,4 @@
+{
+  "model": "gpt-6.1-sol",
+  "reasoningEffort": "low"
+}

package/agent-packs/templates/topolo-coordinators/agents/intakes/engineering/AGENTS.md

@@ -0,0 +1,3 @@
+# Topolo Engineering
+
+Acknowledge the queued request and remain available. If the adapter has not recorded a task, report that dispatch is unavailable; do not take over the implementation. Cloud specialization and task references must be qualified before model work.

package/agent-packs/templates/topolo-coordinators/agents/intakes/engineering/config.json

@@ -0,0 +1,4 @@
+{
+  "model": "gpt-6.1-sol",
+  "reasoningEffort": "low"
+}

package/agent-packs/templates/topolo-coordinators/agents/intakes/operator-01/AGENTS.md

@@ -0,0 +1,3 @@
+# Topolo Operator
+
+Acknowledge the queued request and remain available. If the adapter has not recorded a task, report that dispatch is unavailable; do not take over the implementation. Cloud specialization and task references must be qualified before model work.

package/agent-packs/templates/topolo-coordinators/agents/intakes/operator-01/config.json

@@ -0,0 +1,4 @@
+{
+  "model": "gpt-6.1-sol",
+  "reasoningEffort": "low"
+}

package/agent-packs/templates/topolo-coordinators/pack.json

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": 1,
+  "id": "topolo-coordinators",
+  "version": "1.0.0",
+  "name": "Topolo task coordinators",
+  "purpose": "Three human front doors; specialists are cloud definitions and single-use task workers, not precreated chats.",
+  "agents": [
+    {
+      "set": "intakes",
+      "id": "engineering",
+      "title": "Topolo Engineering",
+      "pinned": true,
+      "position": 0,
+      "sectionName": "Pinned",
+      "aliases": [
+        "engineering"
+      ]
+    },
+    {
+      "set": "intakes",
+      "id": "operator-01",
+      "title": "Topolo Operator",
+      "pinned": true,
+      "position": 1,
+      "sectionName": "Pinned",
+      "aliases": [
+        "operator-01"
+      ]
+    },
+    {
+      "set": "intakes",
+      "id": "cicd",
+      "title": "Topolo CI/CD",
+      "pinned": true,
+      "position": 2,
+      "sectionName": "Pinned",
+      "aliases": [
+        "cicd"
+      ]
+    }
+  ],
+  "dependencies": {
+    "applications": [
+      "app_topolo_agent",
+      "app_topolo_docs",
+      "app_topolo_bytes"
+    ],
+    "capabilities": [
+      "production credential-scoped Topolo CLI or MCP",
+      "conditional canonical task ownership before dispatch"
+    ],
+    "integrationNotes": [
+      "Authenticate on the new machine, install the cloud role catalog and bind the existing activated task dataset. Never restore conversation history or adopt old workers implicitly."
+    ]
+  }
+}

package/dist/chunk-NYDIAYVY.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+// src/lib/claude-desktop-profile.ts
+import * as fs from "fs";
+import * as path from "path";
+import { createHash, randomUUID } from "crypto";
+import { spawnSync } from "child_process";
+function launchClaudeDesktopProfile(options, run = spawnSync) {
+  const root = fs.realpathSync(options.root), uid = process.getuid?.();
+  const ownedDirectory = (value) => {
+    const s = fs.lstatSync(value);
+    if (!path.isAbsolute(value) || fs.realpathSync(value) !== value || !s.isDirectory() || s.isSymbolicLink() || s.uid !== uid || s.mode & 18) throw Error("Exact owned private Desktop profile directories required.");
+    return value;
+  };
+  ownedDirectory(root);
+  const lock = path.join(root, ".claude-profile-launch.lock");
+  let lockfd;
+  if (options.apply) {
+    try {
+      lockfd = fs.openSync(lock, "wx", 384);
+      fs.writeFileSync(lockfd, JSON.stringify({ pid: process.pid }) + "\n");
+      fs.fsyncSync(lockfd);
+    } catch {
+      throw Error("Managed Desktop launch already has an owner; reconcile without duplicate launch.");
+    }
+  }
+  try {
+    const userData = ownedDirectory(options.userData), codeConfig = ownedDirectory(options.codeConfig);
+    if (userData === codeConfig || userData.startsWith(codeConfig + path.sep) || codeConfig.startsWith(userData + path.sep)) throw Error("Desktop and SDK profile directories must be distinct.");
+    const policy = JSON.parse(fs.readFileSync(options.policy, "utf8"));
+    if (policy.format !== "topolo-agent-execution-policy" || policy.pack !== options.pack || policy.installationConsent?.profile !== "full-access" || policy.installationConsent?.principalId === void 0) throw Error("Current reviewed full-access installation policy required for managed Desktop launch.");
+    const app = options.app ?? "/Applications/Claude.app", binary = path.join(app, "Contents/MacOS/Claude");
+    if (!path.isAbsolute(app) || fs.realpathSync(app) !== app || !fs.lstatSync(app).isDirectory() || !fs.lstatSync(binary).isFile()) throw Error("Installed physical Claude application required.");
+    const config = {
+      format: "topolo-claude-desktop-profile",
+      schemaVersion: 1,
+      root,
+      pack: options.pack,
+      userData,
+      codeConfig,
+      app,
+      consentDigest: createHash("sha256").update(JSON.stringify(policy.installationConsent)).digest("hex")
+    };
+    const directory = path.join(root, "claude");
+    fs.mkdirSync(directory, { recursive: true, mode: 448 });
+    ownedDirectory(directory);
+    const file = path.join(directory, "desktop-profile.json");
+    const read = () => {
+      const s = fs.lstatSync(file);
+      if (!s.isFile() || s.isSymbolicLink() || s.uid !== uid || s.mode & 63 || s.nlink !== 1) throw Error("Private owned Desktop profile receipt required.");
+      return JSON.parse(fs.readFileSync(file, "utf8"));
+    };
+    const before = fs.existsSync(file) ? read() : null;
+    if (before && JSON.stringify(before.profile) !== JSON.stringify(config)) throw Error("Managed Desktop profile identity or installation consent changed.");
+    const observed = run("/bin/ps", ["-axo", "pid=,uid=,command="], { encoding: "utf8", timeout: 1e4, maxBuffer: 1048576 });
+    if (observed.error || observed.status !== 0) throw Error("Desktop process ownership observation unavailable.");
+    const matches = String(observed.stdout).split("\n").map((line) => /^\s*(\d+)\s+(\d+)\s+(.+)$/.exec(line)).filter(Boolean).filter((m) => m[3].startsWith(binary + " ") && (m[3].endsWith(" --user-data-dir=" + userData) || m[3].includes(" --user-data-dir=" + userData + " --")));
+    if (matches.length > 1 || matches.some((m) => Number(m[2]) !== uid)) throw Error("Managed Desktop process ownership is ambiguous.");
+    const pid = matches.length ? Number(matches[0][1]) : null;
+    if (!options.apply) return { state: "desktop-profile-launch-preflight", profile: config, pid, nativeStartup: false };
+    if (before?.state === "launch-may-have-effects" && !pid) throw Error("Unacknowledged Desktop launch requires reconciliation; never launch a duplicate.");
+    if (before?.state && !["launch-may-have-effects", "native-profile-verified"].includes(before.state)) throw Error("Unknown Desktop profile launch state.");
+    if (pid && before) return { state: "desktop-profile-existing-unverified", profile: config, pid, nativeStartup: false };
+    if (!pid && before?.pid) {
+      try {
+        process.kill(before.pid, 0);
+        throw Error("Previous managed process is alive.");
+      } catch (error) {
+        if (error.code !== "ESRCH") throw Error("Previous managed Desktop process is not independently proven dead.");
+      }
+    }
+    const help = pid ? null : run("/usr/bin/open", ["-h"], { encoding: "utf8", timeout: 1e4, maxBuffer: 65536 });
+    if (help && (help.error || !String(help.stdout ?? "").concat(String(help.stderr ?? "")).includes("--env"))) throw Error("LaunchServices per-application environment capability unavailable.");
+    const record = { profile: config, operationId: randomUUID(), state: "launch-may-have-effects", history: before ? [...before.history ?? [], { operationId: before.operationId, state: before.state, pid: before.pid ?? null }] : [] };
+    const temporary = file + "." + record.operationId + ".tmp";
+    const fd = fs.openSync(temporary, "wx", 384);
+    try {
+      fs.writeFileSync(fd, JSON.stringify(record) + "\n");
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    if (before && JSON.stringify(read()) !== JSON.stringify(before)) throw Error("Desktop profile receipt changed before launch.");
+    fs.renameSync(temporary, file);
+    const dirfd = fs.openSync(directory, "r");
+    try {
+      fs.fsyncSync(dirfd);
+    } finally {
+      fs.closeSync(dirfd);
+    }
+    if (pid) return { state: "desktop-profile-existing-unverified", profile: config, pid, nativeStartup: false };
+    const launched = run("/usr/bin/open", ["-n", "-a", app, "--env", "CLAUDE_CONFIG_DIR=" + codeConfig, "--args", "--user-data-dir=" + userData], { encoding: "utf8", timeout: 2e4, maxBuffer: 65536 });
+    if (launched.error || launched.status !== 0) throw Error("Desktop LaunchServices acknowledgement missing; preserve launch receipt without replay.");
+    return { state: "desktop-profile-launch-requested", profile: config, operationId: record.operationId, nativeStartup: false };
+  } finally {
+    if (lockfd !== void 0) {
+      fs.closeSync(lockfd);
+      fs.unlinkSync(lock);
+    }
+  }
+}
+function verifyClaudeDesktopProfileNative(expected, pid, app, manager, env) {
+  if (!expected || expected.format !== "topolo-claude-desktop-profile" || expected.schemaVersion !== 1 || app.getName() !== "Claude" || app.getPath("userData") !== expected.userData || manager.userDataPath !== expected.userData || env.CLAUDE_CONFIG_DIR !== expected.codeConfig)
+    throw Error("Native Desktop profile or SDK history root differs; do not import or recreate identities.");
+  return { state: "native-profile-verified", pid, userData: expected.userData, codeConfig: expected.codeConfig };
+}
+function readClaudeDesktopProfile(root) {
+  const file = path.join(root, "claude/desktop-profile.json");
+  if (!fs.existsSync(file)) return null;
+  const s = fs.lstatSync(file);
+  if (!s.isFile() || s.isSymbolicLink() || s.uid !== process.getuid?.() || s.mode & 63 || s.nlink !== 1 || s.size > 1048576) throw Error("Private owned Desktop profile receipt required.");
+  const record = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (record.profile?.root !== root || !["launch-may-have-effects", "native-profile-verified"].includes(record.state)) throw Error("Desktop profile receipt differs.");
+  return record;
+}
+function acknowledgeClaudeDesktopProfile(root, before, proof) {
+  const file = path.join(root, "claude/desktop-profile.json");
+  if (JSON.stringify(readClaudeDesktopProfile(root)) !== JSON.stringify(before) || proof?.state !== "native-profile-verified" || !Number.isSafeInteger(proof.pid) || proof.pid < 1 || proof.userData !== before.profile.userData || proof.codeConfig !== before.profile.codeConfig) throw Error("Native profile acknowledgement or durable custody changed.");
+  if (before.state === "native-profile-verified" && before.pid === proof.pid) return before;
+  const row = { ...before, state: "native-profile-verified", pid: proof.pid, history: [...before.history ?? [], { operationId: before.operationId, state: before.state, pid: before.pid ?? null }] }, temporary = file + "." + randomUUID() + ".tmp";
+  const fd = fs.openSync(temporary, "wx", 384);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(row) + "\n");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  if (JSON.stringify(readClaudeDesktopProfile(root)) !== JSON.stringify(before)) throw Error("Desktop profile changed during acknowledgement.");
+  fs.renameSync(temporary, file);
+  const dir = fs.openSync(path.dirname(file), "r");
+  try {
+    fs.fsyncSync(dir);
+  } finally {
+    fs.closeSync(dir);
+  }
+  return row;
+}
+
+export {
+  launchClaudeDesktopProfile,
+  verifyClaudeDesktopProfileNative,
+  readClaudeDesktopProfile,
+  acknowledgeClaudeDesktopProfile
+};