@tangle-network/agent-app 0.49.32 → 0.49.34

package/bin/tangle-agent/home-maintenance.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env python3
+"""The sole writer of the protected agent home. Installed root-owned, invoked
+through one exact sudo command with Python -I. No caller paths or environment
+choose the home, executable, git configuration, or policy. JSON on stdin/stdout.
+"""
+import datetime
+import fcntl
+import hashlib
+import json
+import os
+import pathlib
+import re
+import signal
+import stat
+import subprocess
+import sys
+import tempfile
+
+BASE = pathlib.Path('/var/lib/tangle-agent')
+ROOT = BASE / 'home'
+STATE = BASE / 'state'
+CONFIG = pathlib.Path('/etc/tangle-agent/home.json')
+GIT = STATE / 'home.git'
+FIXED = {'AGENTS.md', 'SOUL.md', 'IDENTITY.md', 'USER.md', 'MEMORY.md', 'BOOTSTRAP.md'}
+MAX_FILES = 1024
+MAX_TOTAL_BYTES = 8 * 1024 * 1024
+CAPS = {}
+
+
+def protected(path, directory=False):
+    info = path.lstat()
+    if info.st_uid != 0 or info.st_mode & 0o022 or stat.S_ISLNK(info.st_mode):
+        raise ValueError('home ownership or permissions are unsafe')
+    if directory:
+        if not stat.S_ISDIR(info.st_mode):
+            raise ValueError('home directory is not a directory')
+    elif not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
+        raise ValueError('home entry must be a root-owned regular file with one link')
+    return info
+
+
+def load_policy():
+    if os.geteuid() != 0 or len(sys.argv) != 1:
+        raise ValueError('use the installed privileged home command without arguments')
+    for path in [pathlib.Path('/etc'), CONFIG.parent, pathlib.Path('/var'),
+                 pathlib.Path('/var/lib'), BASE, ROOT, STATE]:
+        protected(path, True)
+    if ROOT.stat().st_dev != STATE.stat().st_dev:
+        raise ValueError('home and journal must share one persistent filesystem')
+    protected(CONFIG)
+    policy = json.loads(CONFIG.read_text(encoding='utf8'))
+    uid = policy.get('runtimeUid')
+    if not isinstance(uid, int) or isinstance(uid, bool) or uid <= 0:
+        raise ValueError('home runtime identity is invalid')
+    # sudo supplies SUDO_UID and the exact-command sudoers grant disallows
+    # SETENV. Direct root invocation is reserved for image/operator setup.
+    sudo_uid = os.environ.get('SUDO_UID')
+    if sudo_uid is not None and sudo_uid != str(uid):
+        raise ValueError('this caller does not own this member home')
+    caps = policy.get('caps', {})
+    if set(caps) != FIXED | {'dailyNote', 'skill'} or any(
+        not isinstance(value, int) or isinstance(value, bool) or value <= 0 or value > 32768
+        for value in caps.values()
+    ):
+        raise ValueError('home caps are invalid')
+    CAPS.update(caps)
+    protected(ROOT / 'AGENTS.md')
+    if hashlib.sha256((ROOT / 'AGENTS.md').read_bytes()).hexdigest() != policy.get('agentsSha256'):
+        raise ValueError('platform AGENTS.md attestation failed')
+
+
+def checked(name):
+    if not isinstance(name, str):
+        raise ValueError('home path must be text')
+    if name not in FIXED:
+        note = re.fullmatch(r'memory/(\d{4}-\d{2}-\d{2})\.md', name)
+        skill = re.fullmatch(r'skills/[a-z0-9][a-z0-9-]{0,63}/SKILL\.md', name)
+        if note:
+            datetime.date.fromisoformat(note.group(1))
+        elif not skill:
+            raise ValueError('path is outside the home allowlist')
+    target = ROOT / name
+    current = ROOT
+    for component in pathlib.PurePosixPath(name).parts:
+        current = current / component
+        if current.exists() or current.is_symlink():
+            protected(current, current != target)
+    return target
+
+
+def cap(name):
+    return CAPS[name] if name in FIXED else CAPS['skill' if name.startswith('skills/') else 'dailyNote']
+
+
+def bounded(name, content):
+    checked(name)
+    if not isinstance(content, str) or len(content) > cap(name):
+        raise ValueError('home character budget exceeded')
+    if len(content.encode('utf8')) > cap(name) * 4:
+        raise ValueError('home byte budget exceeded')
+    return content
+
+
+def read(name):
+    path = checked(name)
+    if not path.exists():
+        return ''
+    if path.stat().st_size > cap(name) * 4:
+        raise ValueError('home byte budget exceeded')
+    return bounded(name, path.read_text(encoding='utf8'))
+
+
+def paths():
+    result = []
+    for directory, directories, files in os.walk(ROOT, followlinks=False):
+        for child in directories:
+            protected(pathlib.Path(directory) / child, True)
+        for child in files:
+            name = str((pathlib.Path(directory) / child).relative_to(ROOT))
+            checked(name)
+            result.append(name)
+            if len(result) > MAX_FILES:
+                raise ValueError('home file-count budget exceeded')
+    return sorted(result)
+
+
+def atomic(path, content, mode=0o444):
+    fd, temporary = tempfile.mkstemp(prefix='.home-', dir=STATE)
+    try:
+        with os.fdopen(fd, 'w', encoding='utf8') as output:
+            output.write(content)
+            output.flush()
+            os.fchmod(output.fileno(), mode)
+            os.fsync(output.fileno())
+        os.replace(temporary, path)
+        directory = os.open(path.parent, os.O_DIRECTORY)
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def git(*args):
+    # Neither the caller's PATH/HOME nor git-related environment is inherited.
+    env = {'PATH': '/usr/bin:/bin', 'HOME': '/nonexistent', 'LANG': 'C.UTF-8',
+           'GIT_CONFIG_NOSYSTEM': '1', 'GIT_CONFIG_GLOBAL': '/dev/null', 'GIT_TERMINAL_PROMPT': '0'}
+    result = subprocess.run(['/usr/bin/git', '--git-dir=' + str(GIT), '--work-tree=' + str(ROOT),
+        '-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-c', 'core.fsync=all',
+        '-c', 'user.name=Tangle home', '-c', 'user.email=home@localhost', *args],
+        cwd=ROOT, env=env, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+        timeout=20, check=False)
+    if result.returncode:
+        raise RuntimeError('home git operation failed')
+    return result.stdout.strip()
+
+
+def checkpoint():
+    existing = paths()
+    if sum(len(read(name).encode('utf8')) for name in existing) > MAX_TOTAL_BYTES:
+        raise ValueError('home total-byte budget exceeded')
+    tracked = list(filter(None, git('ls-files', '-z').split('\0')))
+    selected = sorted(set(existing + tracked))
+    for name in selected:
+        checked(name)
+    if selected:
+        git('add', '--all', '--', *selected)
+    changed = bool(git('diff', '--cached', '--name-only'))
+    if changed:
+        git('commit', '-m', 'home: ' + datetime.datetime.now(datetime.timezone.utc).isoformat())
+    return {'commit': git('rev-parse', '--verify', 'HEAD'), 'changed': changed}
+
+
+def apply(updates):
+    # Validate the whole change before writing any document. A durable journal
+    # finishes the same transaction after a crash instead of mixing two nightly
+    # summaries. Neither the journal nor the git metadata is agent-writable.
+    current = {name: read(name) for name in paths()}
+    for name, value in updates.items():
+        checked(name)
+        if name == 'AGENTS.md':
+            raise ValueError('AGENTS.md is platform-owned')
+        if value is None:
+            current.pop(name, None)
+        else:
+            current[name] = bounded(name, value)
+    if len(current) > MAX_FILES or sum(len(value.encode('utf8')) for value in current.values()) > MAX_TOTAL_BYTES:
+        raise ValueError('home total budget exceeded')
+    atomic(STATE / 'pending.json', json.dumps(updates, ensure_ascii=False), 0o600)
+    return finish_pending()
+
+
+def finish_pending():
+    pending = STATE / 'pending.json'
+    if not pending.exists():
+        return None
+    protected(pending)
+    updates = json.loads(pending.read_text(encoding='utf8'))
+    for name, content in updates.items():
+        target = checked(name)
+        if name == 'AGENTS.md':
+            raise ValueError('AGENTS.md is platform-owned')
+        if content is None:
+            if target.exists():
+                target.unlink()
+        else:
+            bounded(name, content)
+            parent = ROOT
+            for component in pathlib.PurePosixPath(name).parts[:-1]:
+                parent = parent / component
+                if not parent.exists():
+                    parent.mkdir(mode=0o755)
+                    parent.chmod(0o755)
+                protected(parent, True)
+            checked(name)
+            atomic(target, content)
+    result = checkpoint()
+    pending.unlink()
+    return result
+
+
+def main():
+    load_policy()
+    os.umask(0o077)
+    raw = sys.stdin.buffer.read(262145)
+    if len(raw) > 262144:
+        raise ValueError('home command input exceeds 262144 bytes')
+    request = json.loads(raw)
+    fields = {'status': set(), 'commit': set(), 'bootstrap': set(), 'read': {'path'},
+              'write': {'path', 'content'}, 'append': {'path', 'content'}, 'delete': {'path'},
+              'consolidate': {'user', 'memory', 'expectedHead'}}
+    if not isinstance(request, dict) or request.get('action') not in fields:
+        raise ValueError('unknown home operation')
+    action = request['action']
+    if set(request) != {'action'} | fields[action]:
+        raise ValueError('invalid home operation fields')
+    lock = STATE / 'home.lock'
+    with lock.open('a') as handle:
+        protected(lock)
+        fcntl.flock(handle, fcntl.LOCK_EX)
+        if not GIT.exists():
+            git('init')
+        protected(GIT, True)
+        finish_pending()
+        if action == 'read':
+            return {'path': request['path'], 'content': read(request['path']),
+                    'commit': git('rev-parse', '--verify', 'HEAD')}
+        if action in {'write', 'append', 'delete'}:
+            name = request['path']
+            content = None if action == 'delete' else request['content']
+            if action == 'append':
+                content = read(name) + content
+            result = apply({name: content})
+            return {**result, 'path': name, 'ownerNoticeRequired': name == 'SOUL.md'}
+        if action == 'bootstrap':
+            if not read('IDENTITY.md').strip():
+                raise ValueError('fill IDENTITY.md before completing bootstrap')
+            return apply({'BOOTSTRAP.md': None})
+        if action == 'consolidate':
+            if request['expectedHead'] != git('rev-parse', '--verify', 'HEAD'):
+                raise ValueError('home changed; reread notes before consolidating')
+            return apply({'USER.md': request['user'], 'MEMORY.md': request['memory']})
+        result = checkpoint()
+        if action == 'status':
+            result['files'] = [{'path': name, 'characters': len(read(name)),
+                'sha256': hashlib.sha256(read(name).encode('utf8')).hexdigest()} for name in paths()]
+        return result
+
+
+if __name__ == '__main__':
+    signal.alarm(30)
+    try:
+        print(json.dumps(main(), ensure_ascii=False))
+    except Exception as error:
+        # Do not reflect file bodies, request data, or subprocess diagnostics.
+        print(json.dumps({'error': str(error) if isinstance(error, (ValueError, RuntimeError))
+                         else type(error).__name__}), file=sys.stderr)
+        sys.exit(1)

package/bin/tangle-agent/home.mjs

@@ -0,0 +1,166 @@
+import { mkdir, open, lstat, readFile, rename, unlink } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { execFile, spawn } from 'node:child_process'
+import { createHash, randomUUID } from 'node:crypto'
+import { promisify } from 'node:util'
+
+export const PROTECTED_HOME = '/var/lib/tangle-agent/home'
+const BASE = '/var/lib/tangle-agent'
+const STATE = `${BASE}/state`
+const CONFIG = '/etc/tangle-agent/home.json'
+const HELPER = '/usr/local/libexec/tangle-agent-home.py'
+const run = promisify(execFile)
+const cleanEnv = { PATH: '/usr/bin:/bin', LANG: 'C.UTF-8' }
+
+async function protectedEntry(path, directory = false) {
+  const info = await lstat(path)
+  if (info.uid !== 0 || (info.mode & 0o022) || info.isSymbolicLink() ||
+      (directory ? !info.isDirectory() : !info.isFile() || info.nlink !== 1)) {
+    throw new Error(`Unsafe protected home installation: ${path}`)
+  }
+  return info
+}
+
+/** One installed, exact-command sudo capability. No shell and no caller environment. */
+export async function homeOperation(request, signal) {
+  signal?.throwIfAborted()
+  const input = JSON.stringify(request)
+  if (Buffer.byteLength(input) > 262144) throw new Error('Home request is too large')
+  await protectedEntry(HELPER)
+  return new Promise((resolve, reject) => {
+    const child = spawn('/usr/bin/sudo', ['-n', '--', '/usr/bin/python3', '-I', HELPER], {
+      cwd: '/', env: cleanEnv, stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    let output = '', errorOutput = '', size = 0, inputFailed = false, timedOut = false
+    child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
+    const stop = () => child.kill('SIGTERM')
+    const timer = setTimeout(() => { timedOut = true; stop() }, 35_000)
+    timer.unref()
+    signal?.addEventListener('abort', stop, { once: true })
+    child.stdout.on('data', bytes => {
+      size += Buffer.byteLength(bytes)
+      if (size > 1024 * 1024) stop()
+      else output += bytes.toString('utf8')
+    })
+    child.stderr.on('data', bytes => { if (errorOutput.length < 2048) errorOutput += bytes.toString('utf8') })
+    child.stdin.on('error', () => { inputFailed = true })
+    child.once('error', finishError)
+    child.once('close', (code, killed) => {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', stop)
+      if (signal?.aborted) return reject(signal.reason)
+      if (code !== 0 || killed || inputFailed || timedOut || size > 1024 * 1024) {
+        let detail = 'Home operation failed or is unconfirmed; inspect home_status before retrying a write'
+        try { const value = JSON.parse(errorOutput); if (typeof value.error === 'string') detail = value.error }
+        catch { detail = 'Protected home returned no validation receipt; inspect home_status before retrying a write' }
+        return reject(new Error(detail))
+      }
+      try { resolve(JSON.parse(output)) } catch { reject(new Error('Invalid protected home response')) }
+    })
+    function finishError(error) {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', stop)
+      reject(new Error('The protected home command could not start', { cause: error }))
+    }
+    child.stdin.end(input)
+  })
+}
+
+/** The runtime cannot create or repair this boundary as its own UID. */
+export async function initializeHome(directoryName) {
+  if (directoryName !== PROTECTED_HOME || typeof process.getuid !== 'function' || process.getuid() === 0) {
+    throw new Error('General agents require the installed protected home and a non-root runtime UID')
+  }
+  for (const directory of ['/var', '/var/lib', BASE, PROTECTED_HOME, '/etc', '/etc/tangle-agent', '/usr/local/libexec']) {
+    await protectedEntry(directory, true)
+  }
+  await protectedEntry(CONFIG)
+  const policy = JSON.parse(await readFile(CONFIG, 'utf8'))
+  if (policy.runtimeUid !== process.getuid()) throw new Error('Protected home belongs to another runtime UID')
+  await protectedEntry(`${PROTECTED_HOME}/AGENTS.md`)
+  const digest = createHash('sha256').update(await readFile(`${PROTECTED_HOME}/AGENTS.md`)).digest('hex')
+  if (digest !== policy.agentsSha256) throw new Error('Platform AGENTS.md attestation failed')
+  await homeOperation({ action: 'status' })
+  return PROTECTED_HOME
+}
+
+export async function checkpointHome(directoryName, signal) {
+  if (directoryName !== PROTECTED_HOME) throw new Error('Invalid protected home')
+  return { home: PROTECTED_HOME, ...await homeOperation({ action: 'commit' }, signal) }
+}
+
+/** Image/operator install only. Uses the same canonical profile seed records. */
+export async function installProtectedHome(runtimeUser) {
+  if (process.getuid?.() !== 0 || !/^[a-z_][a-z0-9_-]{0,31}$/.test(runtimeUser ?? '')) {
+    throw new Error('install-home requires root and an explicit non-root runtime user')
+  }
+  const uid = Number((await run('/usr/bin/id', ['-u', runtimeUser])).stdout.trim())
+  const gid = Number((await run('/usr/bin/id', ['-g', runtimeUser])).stdout.trim())
+  if (!Number.isSafeInteger(uid) || uid <= 0 || !Number.isSafeInteger(gid) || gid < 0) throw new Error('Invalid runtime UID/GID')
+  for (const [directory, mode] of [[BASE, 0o755], [PROTECTED_HOME, 0o755], [STATE, 0o700],
+    ['/etc/tangle-agent', 0o755], ['/usr/local/libexec', 0o755], ['/etc/sudoers.d', 0o750]]) {
+    await mkdir(directory, { recursive: true, mode })
+    await protectedEntry(directory, true)
+  }
+  if ((await lstat(STATE)).dev !== (await lstat(PROTECTED_HOME)).dev) throw new Error('Home and journal must share one persistent filesystem')
+  async function replace(path, body, mode) {
+    const temporary = join(dirname(path), `.tangle-${randomUUID()}`)
+    const file = await open(temporary, 'wx', mode)
+    try {
+      await file.writeFile(body)
+      await file.sync()
+      await rename(temporary, path)
+    } finally {
+      await file.close()
+      try { await unlink(temporary) } catch (error) { if (error.code !== 'ENOENT') throw error }
+    }
+  }
+  const { defaultHomeFiles, DEFAULT_HOME_LIMITS } = await import('../../dist/hosted-agent/index.js')
+  const seeds = defaultHomeFiles().filter(mount => mount.path !== '.tangle/home.py')
+  const agents = seeds.find(mount => mount.path === 'AGENTS.md')?.resource.content
+  if (!agents) throw new Error('The installed package has no canonical AGENTS.md')
+  let initialized = false
+  try { await protectedEntry(`${STATE}/initialized`); initialized = true }
+  catch (error) { if (error.code !== 'ENOENT') throw error }
+  for (const mount of seeds) {
+    if (mount.resource.kind !== 'inline' || !Object.hasOwn(DEFAULT_HOME_LIMITS, mount.path)) throw new Error('Unsupported home seed')
+    if (initialized && mount.path !== 'AGENTS.md') continue
+    const path = `${PROTECTED_HOME}/${mount.path}`
+    try {
+      await protectedEntry(path)
+      if (mount.path !== 'AGENTS.md') continue
+    } catch (error) { if (error.code !== 'ENOENT') throw error }
+    await replace(path, mount.resource.content, 0o444)
+  }
+  await replace(CONFIG, JSON.stringify({ runtimeUid: uid, caps: DEFAULT_HOME_LIMITS,
+    agentsSha256: createHash('sha256').update(agents).digest('hex') }), 0o444)
+  await replace(HELPER, await readFile(new URL('./home-maintenance.py', import.meta.url)), 0o444)
+  // Verify inherited sudoers ordering rather than silently leaving a broad grant.
+  const policyFile = '/etc/sudoers.d/zz-tangle-agent-home'
+  await replace(policyFile, `Defaults:${runtimeUser} env_reset,secure_path="/usr/bin:/bin"\n` +
+    `${runtimeUser} ALL=(ALL:ALL) !ALL\n` +
+    `${runtimeUser} ALL=(root) NOPASSWD: NOSETENV: /usr/bin/python3 -I ${HELPER}\n`, 0o440)
+  await run('/usr/sbin/visudo', ['-cf', policyFile], { env: cleanEnv })
+  let rootCommandDenied = false
+  try { await run('/usr/bin/sudo', ['-n', '--', '/usr/bin/id', '-u'], { uid, gid, env: cleanEnv }) }
+  catch (error) { if (error.code === 1) rootCommandDenied = true; else throw error }
+  if (!rootCommandDenied) throw new Error('Runtime still has a broad sudo grant; refuse the image')
+  const status = await new Promise((resolve, reject) => {
+    const child = spawn('/usr/bin/sudo', ['-n', '--', '/usr/bin/python3', '-I', HELPER],
+      { uid, gid, cwd: '/', env: cleanEnv, stdio: ['pipe', 'pipe', 'pipe'] })
+    let output = ''
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', bytes => { output += bytes.toString() })
+    child.stderr.resume()
+    child.on('error', reject)
+    child.on('close', code => {
+      try { if (code !== 0) throw new Error('Privileged home command did not pass its real UID probe'); resolve(JSON.parse(output)) }
+      catch (error) { reject(error) }
+    })
+    child.stdin.end(JSON.stringify({ action: 'status' }))
+  })
+  if (!status.commit) throw new Error('Protected home has no Git checkpoint')
+  await replace(`${STATE}/initialized`, 'tangle-agent-home-v2\n', 0o400)
+  return { home: PROTECTED_HOME, runtimeUid: uid, commit: status.commit }
+}

package/bin/tangle-agent/provision.mjs

@@ -0,0 +1,168 @@
+import { readFile } from 'node:fs/promises'
+import { z } from 'zod'
+import { Sandbox } from '@tangle-network/sandbox/core'
+import { HubClient } from '@tangle-network/hub-sdk'
+import { agentProfileSchema, defineAgentProfilePublicConfig as publicValue,
+  defineAgentProfileSecretRef as secretRef, mergeAgentProfiles } from '@tangle-network/agent-interface'
+import { GENERAL_AGENT_MODEL, GENERAL_AGENT_SYSTEM_PROMPT, DEFAULT_AGENT_HOME,
+  withDefaultAgentHome, agentHomeWorkflows } from '../../dist/hosted-agent/index.js'
+
+const name = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/)
+const role = z.enum(['owner', 'manager', 'staff', 'vendor', 'finance', 'practitioner'])
+const envKey = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/)
+const domain = z.string().regex(/^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9-]+$/)
+const protectedProfile = z.record(z.string(), z.unknown()).superRefine((value, context) => {
+  if (Object.hasOwn(value, 'interactions')) context.addIssue({ code: 'custom',
+    message: 'A general-agent profile cannot override backend permission interactions' })
+}).transform(value => agentProfileSchema.parse(value))
+const backend = z.object({ type: z.literal('opencode').optional(), profile: protectedProfile }).strict()
+  .transform(value => ({ ...value, type: 'opencode', interactions: { permission: true } }))
+const configSchema = z.object({
+  version: z.literal(1),
+  keyPrefix: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:@-]{0,99}$/),
+  environment: z.string().min(1),
+  model: z.string().min(1).default(GENERAL_AGENT_MODEL),
+  imageModel: z.string().min(1), videoModel: z.string().min(1),
+  runtimeModule: z.string().regex(/^\//).default('/opt/tangle-agent/node_modules/@tangle-network/agent-app/bin/tangle-agent.mjs'),
+  home: z.literal(DEFAULT_AGENT_HOME).default(DEFAULT_AGENT_HOME),
+  chromium: z.string().regex(/^\//),
+  proxyEnv: envKey.default('HTTPS_PROXY'), routerKeyEnv: envKey.default('OPENCODE_MODEL_API_KEY'),
+  allowDomains: z.array(domain).max(95).default([]),
+  resources: z.object({ cpuCores: z.number().int().min(2).max(64).default(2),
+    memoryMB: z.number().int().min(4096).max(262144).default(4096),
+    diskGB: z.number().int().min(10).max(2048).default(20) }).strict().prefault({}),
+  baseProfile: protectedProfile.prefault({}),
+  scopedServers: z.record(z.string(), z.array(name).min(1).max(16)).default({}),
+  members: z.array(z.object({ address: z.string().regex(/^\+[1-9]\d{6,14}$/), role,
+    label: z.string().min(1).max(60), backend: backend.optional(),
+    secretNames: z.array(z.string().regex(/^TANGLE_AGENT_PRODUCT_[A-Z0-9_]{1,96}$/)).max(16).optional() }).strict()).min(1).max(50),
+  lines: z.array(z.object({ id: z.string().regex(/^ln_[A-Za-z0-9_-]+$/),
+    transport: z.enum(['imessage', 'whatsapp']),
+    voice: z.object({ ph0nyConnectionId: z.string().min(1), ph0nyAgentId: z.string().min(1),
+      outboundFrom: z.string().regex(/^\+[1-9]\d{6,14}$/) }).strict().optional(),
+  }).strict()).min(1).max(8),
+  // No guessed owner timezone. Supplying this installs both disabled jobs;
+  // the operator enables them after consent and the deployed boundary proof.
+  heartbeat: z.object({ lineId: z.string().min(1), owner: z.string().regex(/^\+[1-9]\d{6,14}$/),
+    cron: z.literal('0 8-22 * * *').default('0 8-22 * * *'), timezone: z.string().min(1),
+    prompt: z.string().min(1).max(8000).optional(),
+  }).strict(),
+}).strict()
+
+export function buildGeneralAgent(configInput) {
+  const config = configSchema.parse(configInput)
+  if (new Set(config.members.map(member => member.address)).size !== config.members.length ||
+      new Set(config.lines.map(line => line.id)).size !== config.lines.length) throw new Error('Members and lines must be unique')
+  if (config.members.filter(member => member.role === 'owner').length !== 1) throw new Error('Exactly one enrolled owner is required for approvals')
+  if (config.baseProfile.prompt?.systemPrompt) throw new Error('Business presets add instructions and skills, not a replacement system prompt')
+  for (const line of config.lines) if (line.voice && line.transport !== 'imessage') throw new Error('Hub voice requires the Inkbox iMessage line')
+  const roles = {}, grants = {}, members = {}
+  for (const member of config.members) {
+    const general = ['owner', 'manager'].includes(member.role)
+    roles[member.role] = { context: 'own', tools: 'act' }
+    if (general) grants[member.role] = { kind: 'general' }
+    else {
+      const servers = config.scopedServers[member.role]
+      if (!servers?.length || !member.backend) throw new Error(`Scoped ${member.role} needs an enrolled product backend and named MCP servers`)
+      grants[member.role] = { kind: 'scoped', mcpServers: servers }
+    }
+    if (member.backend) members[member.address] = { backend: member.backend,
+      ...(member.secretNames ? { secretNames: member.secretNames } : {}) }
+  }
+  const substrate = agentProfileSchema.parse({
+    name: 'tangle-agent-v1', model: { default: config.model },
+    prompt: { systemPrompt: GENERAL_AGENT_SYSTEM_PROMPT, instructions: [
+      `Your durable home is ${config.home}. It is preinstalled and root-owned. Read AGENTS.md and SOUL.md there. Use home_read, home_write, home_append, home_status, home_bootstrap and home_consolidate. Ordinary shell and code remain available outside this protected directory. Never create an unprotected replacement home.`,
+      'The protected writer enforces Unicode-character, byte and file-count caps before any memory mutation. Every successful mutation returns a Git commit. A SOUL.md change requires an immediate owner notice. Keep credentials and third-party private data out of memory.',
+      'Use the published tangle_agent tools for Router search/read, Browser Agent and image/video generation. Use native computer-use tools for the virtual display and explicitly mounted Hub connections for email, calendar and ph0ny. Do not substitute direct provider APIs or disable the allowlist proxy.',
+      'The platform scheduler owns reminders and maintenance. The hourly heartbeat and nightly consolidation use the same consenting owner session. A queued workflow is not a completed reminder; report the actual workflow and eventual line receipts.',
+    ] },
+    mcp: { tangle_agent: { transport: 'stdio', command: 'node',
+      args: [publicValue(config.runtimeModule), publicValue('serve')],
+      env: {
+        TANGLE_AGENT_ROUTER_KEY: secretRef(config.routerKeyEnv),
+        TANGLE_AGENT_BROWSER_PROXY: secretRef(config.proxyEnv),
+        TANGLE_AGENT_HOME: publicValue(config.home), TANGLE_AGENT_CHROMIUM: publicValue(config.chromium),
+        TANGLE_AGENT_MODEL: publicValue(config.model), TANGLE_AGENT_IMAGE_MODEL: publicValue(config.imageModel),
+        TANGLE_AGENT_VIDEO_MODEL: publicValue(config.videoModel),
+      }, enabled: true } },
+    resources: { failOnError: true },
+  })
+  const composed = mergeAgentProfiles(config.baseProfile, substrate)
+  if (!composed) throw new Error('General profile composition failed')
+  const profile = withDefaultAgentHome(composed)
+  for (const line of config.lines) {
+    if (!line.voice) continue
+    const { ph0nyConnectionId, ph0nyAgentId, outboundFrom } = line.voice
+    const capabilities = ['phony.start_outbound_call', 'phony.get_call']
+    const existing = profile.connections?.find(value => value.connectionId === ph0nyConnectionId)
+    if (existing) {
+      if (!existing.capabilities.includes('*')) existing.capabilities = [...new Set([...existing.capabilities, ...capabilities])]
+    } else profile.connections = [...(profile.connections ?? []), { connectionId: ph0nyConnectionId, capabilities }]
+    profile.prompt.instructions.push(`Voice line ${line.id}: use the connected ph0ny tools with agentId ${ph0nyAgentId} and the operator-attested fromNumber ${outboundFrom}. The enrolled owner destination is ${config.members.find(member => member.role === 'owner').address}. Wait for owner approval and actual consent. The call hook rechecks membership and binds the destination member's role and private workspace. Report the actual call id and connected/completed state, not a submission alone.`)
+  }
+  agentProfileSchema.parse(profile)
+  const respond = { kind: 'agent', backend: {
+    type: 'opencode', profile, interactions: { permission: true },
+  }, rolePolicy: { version: 1, roles: grants, members } }
+  const attachments = config.lines.map(line => ({
+    number: line.id, mode: 'shared', unknownSenders: 'reject', roles,
+    members: config.members.map(({ address, role, label }) => ({ address, role, label })),
+    respond, clientReference: config.keyPrefix,
+    instance: { keyPrefix: config.keyPrefix, create: {
+      name: 'tangle-agent-v1', environment: config.environment, ownerContext: 'isolated', capabilities: ['computer_use'],
+      resources: config.resources,
+      egressPolicy: { mode: 'strict', includeImplicitDomains: false,
+        allowDomains: [...new Set(['router.tangle.tools', 'id.tangle.tools', ...config.allowDomains])] },
+      idleTimeoutSeconds: 600, maxLifetimeSeconds: 90 * 86400, deleteAfterStoppedSeconds: 90 * 86400,
+    } },
+  }))
+  const h = config.heartbeat
+  if (!config.lines.some(line => line.id === h.lineId) ||
+      !config.members.some(member => member.address === h.owner && member.role === 'owner')) {
+    throw new Error('Heartbeat must target a configured line and its enrolled owner')
+  }
+  const workflows = agentHomeWorkflows({ instanceKey: config.keyPrefix, lineId: h.lineId,
+    ownerAddress: h.owner, timeZone: h.timezone, heartbeatInstructions: h.prompt })
+  return { config, attachments, workflows, heartbeat: workflows.find(job => job.purpose === 'heartbeat').yaml }
+}
+
+export async function provision(path, apply = false) {
+  const plan = buildGeneralAgent(JSON.parse(await readFile(path, 'utf8')))
+  if (!apply) {
+    console.log(JSON.stringify({ attachments: plan.attachments, workflows: plan.workflows }, null, 2))
+    return
+  }
+  const key = process.env.TANGLE_API_KEY
+  if (!key) throw new Error('TANGLE_API_KEY must be supplied to the trusted operator, never the agent image')
+  const sandbox = new Sandbox({ apiKey: key, baseUrl: process.env.SANDBOX_BASE_URL ?? 'https://sandbox.tangle.tools' })
+  const hub = new HubClient({ apiKey: key, baseUrl: 'https://id.tangle.tools' })
+  // Validate all owned transports first. SDK attach is idempotent for the
+  // exact config and refuses a changed active attachment. Never auto-detach.
+  for (const line of plan.config.lines) {
+    const current = await sandbox.lines.get(line.id)
+    if (current.transport !== line.transport || current.status !== 'active') throw new Error('Line is not an active owned line on the declared transport')
+  }
+  const receipts = []
+  for (let i = 0; i < plan.attachments.length; i++) {
+    const attachment = await sandbox.lines.attach(plan.attachments[i])
+    const line = plan.config.lines[i]
+    if (line.voice) {
+      const { ph0nyConnectionId, ph0nyAgentId } = line.voice
+      await sandbox.lines.enableVoice(line.id, { ph0nyConnectionId, ph0nyAgentId })
+    }
+    receipts.push({ line: await sandbox.lines.get(line.id), attachment })
+    console.log(JSON.stringify({ state: 'attached', lineId: line.id, attachmentId: attachment.id }))
+  }
+  const existing = await hub.workflows.list()
+  const workflows = []
+  for (const job of plan.workflows) {
+    const matches = existing.filter(value => value.name === job.name)
+    if (matches.length > 1) throw new Error('Duplicate home workflows exist; refuse to create another')
+    const workflow = matches.length ? await hub.workflows.update(matches[0].id, job.yaml)
+      : await hub.workflows.create(job.yaml)
+    workflows.push({ purpose: job.purpose, workflow })
+  }
+  console.log(JSON.stringify({ receipts, workflows,
+    next: 'Do not use this attachment until ADC checks exact native approval on each member instance and the local allow/deny effect-sink proof passes. Then the owner must text first. Verify the actual runtime UID, protected home, scoped vendor denial and installed tools before enabling the two disabled Hub workflows.' }, null, 2))
+}