@davait/aipictury 1.9.2

package/ext/prefs.js

@@ -0,0 +1,157 @@
+'use strict'
+// Settings kept in files, at three levels — as Claude Code keeps them, and in the same shape:
+//
+//   user     ~/.aipictury/settings.json             everywhere you work
+//   project  <workspace>/.aipictury/settings.json   shared with the project (committed)
+//   local    <workspace>/.aipictury/settings.local.json   yours, in this project only
+//
+// Claude Code's own files are read too, and never written: ~/.claude/settings.json,
+// .claude/settings.json and .claude/settings.local.json — so rules and hooks written for it
+// apply here as well.
+//
+// Merging: lists add up (permission rules, hooks per event, disabled servers); objects are
+// merged key by key (enabledPlugins, skillVisibility, sandbox); for a single value the more
+// specific level wins (local over project over user; AIPictury's file over Claude Code's at the
+// same level). Deny beats ask beats allow — that is decided where rules are matched.
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { home } = require('./sessions')
+
+const LEVELS = ['user', 'project', 'local']
+// Lists that add up across levels, as permission rules do.
+const LISTS = new Set(['disabledMcpServers', 'disabledMcpjsonServers', 'enabledMcpjsonServers'])
+const isPlain = (v) => !!v && typeof v === 'object' && !Array.isArray(v)
+
+/** Every settings file that applies, least specific first. */
+function sources(folder) {
+  const ours = {
+    user: path.join(home(), 'settings.json'),
+    project: folder && path.join(folder, '.aipictury', 'settings.json'),
+    local: folder && path.join(folder, '.aipictury', 'settings.local.json'),
+  }
+  const claude = {
+    user: path.join(process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'), 'settings.json'),
+    project: folder && path.join(folder, '.claude', 'settings.json'),
+    local: folder && path.join(folder, '.claude', 'settings.local.json'),
+  }
+  const out = []
+  for (const level of LEVELS) {
+    if (claude[level]) out.push({ level, file: claude[level], editable: false, origin: 'Claude Code' })
+    if (ours[level]) out.push({ level, file: ours[level], editable: true, origin: 'AIPictury' })
+  }
+  return out
+}
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return null }
+}
+
+// Read at every tool call (rules, hooks): kept until one of the files changes.
+const cache = new Map()
+const signature = (list) => list.map((s) => { try { const st = fs.statSync(s.file); return `${s.file}:${st.mtimeMs}:${st.size}` } catch { return `${s.file}:-` } }).join('|')
+
+/** The settings, merged, and where each came from. */
+function load(folder) {
+  const list = sources(folder)
+  const key = `${folder || ''}`
+  const sig = signature(list)
+  const hit = cache.get(key)
+  if (hit && hit.sig === sig) return hit.value
+  const value = loadFresh(list)
+  cache.set(key, { sig, value })
+  return value
+}
+
+function loadFresh(list) {
+  const found = list.map((s) => ({ ...s, data: readJson(s.file) }))
+  const merged = { permissions: { allow: [], ask: [], deny: [] }, hooks: {} }
+  for (const s of found) {
+    if (!s.data || typeof s.data !== 'object') continue
+    for (const [key, value] of Object.entries(s.data)) {
+      if (key === 'permissions' && value && typeof value === 'object') {
+        for (const kind of ['allow', 'ask', 'deny']) {
+          for (const rule of Array.isArray(value[kind]) ? value[kind] : []) {
+            merged.permissions[kind].push({ rule: String(rule), level: s.level, file: s.file, editable: s.editable })
+          }
+        }
+        if (value.defaultMode) merged.permissions.defaultMode = value.defaultMode
+        if (Array.isArray(value.additionalDirectories)) {
+          merged.permissions.additionalDirectories = [...(merged.permissions.additionalDirectories || []), ...value.additionalDirectories]
+        }
+      } else if (key === 'hooks' && value && typeof value === 'object') {
+        for (const [event, groups] of Object.entries(value)) {
+          for (const group of Array.isArray(groups) ? groups : []) {
+            (merged.hooks[event] ||= []).push({ ...group, level: s.level, file: s.file, editable: s.editable })
+          }
+        }
+      } else if (key === 'env' && value && typeof value === 'object') {
+        merged.env = { ...(merged.env || {}), ...value }
+      } else if (isPlain(value) && isPlain(merged[key])) {
+        merged[key] = { ...merged[key], ...value }   // enabledPlugins, sandbox…: merged key by key
+      } else if (Array.isArray(value) && LISTS.has(key)) {
+        merged[key] = [...new Set([...(merged[key] || []), ...value])]
+      } else {
+        merged[key] = value                    // later (more specific) wins
+      }
+    }
+  }
+  return { merged, sources: found }
+}
+
+/** The file for a level (always AIPictury's own: Claude Code's are never written). */
+function fileFor(folder, level) {
+  const s = sources(folder).find((x) => x.level === level && x.editable)
+  if (!s) throw new Error(`no ${level} settings file here (open a folder)`)
+  return s.file
+}
+
+function edit(folder, level, change) {
+  const file = fileFor(folder, level)
+  const data = readJson(file) || {}
+  change(data)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const tmp = `${file}.${process.pid}.tmp`
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`)
+  fs.renameSync(tmp, file)
+  if (level === 'local') keepOutOfGit(folder)
+  return file
+}
+
+/** The local file is personal: it is added to the project's .gitignore when there is one. */
+function keepOutOfGit(folder) {
+  const ignore = path.join(folder, '.gitignore')
+  try {
+    const text = fs.existsSync(ignore) ? fs.readFileSync(ignore, 'utf8') : null
+    if (text === null || /(^|\n)\.aipictury\/settings\.local\.json\s*(\n|$)/.test(text)) return
+    fs.appendFileSync(ignore, `${text.endsWith('\n') || !text ? '' : '\n'}.aipictury/settings.local.json\n`)
+  } catch { /* not ours to insist on */ }
+}
+
+function addRule(folder, level, kind, rule) {
+  if (!['allow', 'ask', 'deny'].includes(kind)) throw new Error(`a rule is allow, ask or deny, not ${kind}`)
+  const clean = String(rule || '').trim()
+  if (!clean) throw new Error('an empty rule')
+  return edit(folder, level, (data) => {
+    data.permissions ||= {}
+    const list = (data.permissions[kind] ||= [])
+    if (!list.includes(clean)) list.push(clean)
+  })
+}
+
+function removeRule(folder, level, kind, rule) {
+  return edit(folder, level, (data) => {
+    const list = data.permissions?.[kind]
+    if (Array.isArray(list)) data.permissions[kind] = list.filter((r) => r !== rule)
+  })
+}
+
+/** Sets one top-level value (an output style, skill visibility…) at a level. */
+function set(folder, level, key, value) {
+  return edit(folder, level, (data) => {
+    if (value === undefined) delete data[key]
+    else data[key] = value
+  })
+}
+
+module.exports = { load, sources, addRule, removeRule, set, edit, fileFor, LEVELS }

package/ext/remote.js

@@ -0,0 +1,170 @@
+'use strict'
+// Remote control: a conversation of this editor carried on from the web app — a phone included —
+// while it keeps running here, as Claude Code's Remote Control. The extension connects to the
+// AIPictury server (/ws/remote/host) and sends the conversation's state whenever it changes;
+// what the user does in the browser comes back as commands: a message, an approval, an answer,
+// a plan's verdict, Stop. The agent runs here, under this editor's rules.
+//
+// The link carries a key only the editor and the link know (the server keeps its hash). From the
+// browser one can say yes or no once, but not save a standing rule, change the permission mode
+// or run a slash command: those stay in VS Code.
+// No VS Code here: the panel is handed in.
+const crypto = require('crypto')
+
+const ITEMS = 60                       // transcript entries sent (the latest)
+const TEXT_CAP = 8000                  // characters of one entry
+const LIVE_CAP = 20_000
+const DEBOUNCE = 150
+const RETRY = [1000, 2000, 5000, 10_000, 30_000]
+
+const cut = (text, n) => { const t = String(text ?? ''); return t.length > n ? `${t.slice(0, n)}…` : t }
+
+/** One line saying what a tool call did, for the remote view. */
+function toolLabel(t) {
+  const a = t.args || {}
+  return cut(a.command || a.path || a.url || a.pattern || a.query || a.description || a.title || a.action || '', 160)
+}
+
+/** What an approval asks, for the remote view: kind, the command or file, why. */
+function approvalOf(id, request = {}) {
+  return {
+    id, kind: request.kind,
+    tool: request.tool, command: cut(request.command, 2000), path: request.path, site: request.site,
+    because: request.because, description: request.description,
+    args: request.kind === 'tool' || request.kind === 'mcp' ? cut(JSON.stringify(request.args || {}), 1200) : undefined,
+    // An edit as a diff: each changed part, its removed lines (-) and added ones (+), from line n.
+    diff: request.kind === 'edit' ? cut((request.hunks || []).map((h) => [`@@ line ${h.line}`, ...h.removed.map((l) => `- ${l}`),
+      ...h.added.map((l) => `+ ${l}`)].join('\n')).join('\n') || request.after, 6000) : undefined,
+  }
+}
+
+/** The conversation as the remote view shows it. */
+function snapshot(panel, live) {
+  const items = (panel.transcript || []).slice(-ITEMS).map((t) => {
+    if (t.kind === 'user' || t.kind === 'assistant') return { kind: t.kind, text: cut(t.text, TEXT_CAP), at: t.at }
+    if (t.kind === 'tool') return { kind: 'tool', tool: t.tool, status: t.status, label: toolLabel(t), result: cut(typeof t.result === 'string' ? t.result : '', 400) }
+    if (t.kind === 'error') return { kind: 'error', text: cut(t.text || t.error, 1000) }
+    return null
+  }).filter(Boolean)
+  return {
+    title: panel.title || panel.aiTitle || 'New conversation',
+    running: !!panel.abort,
+    live: cut(live, LIVE_CAP),
+    items,
+    approvals: [...(panel.approvals || new Map())].map(([id, p]) => approvalOf(id, p.request)),
+    question: panel.pendingAsk ? { id: panel.pendingAsk.id, questions: panel.pendingAsk.questions } : null,
+    plan: panel.pendingPlan ? { id: panel.pendingPlan.id, plan: cut(panel.pendingPlan.plan, 20_000) } : null,
+    queue: (panel.queue || []).map((q) => cut(q.text, 400)),
+  }
+}
+
+class RemoteLink {
+  /** `panel`: the AgentPanel; `server`: its http(s) address. */
+  constructor(panel, server, { log = () => {}, onViewers = () => {}, webApp = 'https://aipictury.com', token = async () => null } = {}) {
+    this.webApp = webApp
+    this.token = token                  // the account's ID token: the server may ask for it
+    this.panel = panel
+    this.server = server.replace(/\/+$/, '')
+    this.id = crypto.randomUUID()
+    this.key = crypto.randomBytes(24).toString('base64url')
+    this.log = log
+    this.onViewers = onViewers
+    this.live = ''
+    this.viewers = 0
+    this.active = false
+    this.tries = 0
+  }
+
+  /** The address to open in a browser: the key travels in the fragment, never to a server log. */
+  /** The address to open: the web app at aipictury.com (aipictury.webApp), with the conversation,
+   *  its key and the GPU server it is on — all in the fragment, which never reaches a server's log. */
+  get url() {
+    const web = (this.webApp || 'https://aipictury.com').replace(/\/+$/, '')
+    return `${web}/#remote/${this.id}.${this.key}~${Buffer.from(this.server).toString('base64url')}`
+  }
+
+  start() {
+    this.active = true
+    const post = this.panel.post.bind(this.panel)
+    this.restorePost = () => { this.panel.post = post }
+    this.panel.post = (message) => {
+      post(message)
+      if (message.type === 'delta') this.live += message.text || ''
+      if (message.type === 'begin' || message.type === 'turn' || message.type === 'end') this.live = ''
+      this.schedule()
+    }
+    this.connect()
+    return this
+  }
+
+  async connect() {
+    if (!this.active) return
+    const token = await this.token().catch(() => null)
+    if (!this.active) return
+    const ws = new WebSocket(`${this.server.replace(/^http/, 'ws')}/ws/remote/host${token ? `?token=${encodeURIComponent(token)}` : ''}`)
+    this.ws = ws
+    ws.onopen = () => { ws.send(JSON.stringify({ type: 'hello', id: this.id, key: this.key })) }
+    ws.onmessage = (event) => {
+      let msg
+      try { msg = JSON.parse(String(event.data)) } catch { return }
+      if (msg.type === 'ready') { this.tries = 0; this.connected = true; this.setViewers(msg.viewers); this.send() }
+      if (msg.type === 'viewers') this.setViewers(msg.viewers)
+      if (msg.type === 'command') this.command(msg.command || {}).catch((error) => this.log(`remote command failed: ${error.message}`))
+    }
+    ws.onclose = (event) => {
+      this.connected = false
+      if (!this.active || event.code === 4403 || event.code === 4409) return
+      const wait = RETRY[Math.min(this.tries, RETRY.length - 1)]
+      this.tries += 1
+      this.retry = setTimeout(() => this.connect(), wait)
+    }
+    ws.onerror = () => {}                                   // onclose follows, and retries
+  }
+
+  setViewers(n) { this.viewers = n || 0; this.onViewers(this.viewers) }
+
+  schedule() {
+    if (!this.connected || this.pending) return
+    this.pending = setTimeout(() => { this.pending = null; this.send() }, DEBOUNCE)
+  }
+
+  send() {
+    if (this.ws?.readyState !== 1) return
+    this.ws.send(JSON.stringify({ type: 'state', state: snapshot(this.panel, this.live) }))
+  }
+
+  /** What the browser asked for. Only what a user in the panel could do with one click. */
+  async command(c) {
+    const p = this.panel
+    if (c.type === 'message') {
+      const text = String(c.text || '').trim()
+      if (!text) return
+      if (/^[/#]/.test(text)) { p.say('from the browser: slash commands and # rules work in VS Code itself — sent as a message they would not run', 'remote'); return }
+      await p.ask(text)
+    } else if (c.type === 'approval') {
+      // Yes or no to this one call — a standing yes is saved from VS Code only.
+      if (!['allow', 'deny'].includes(c.decision)) return
+      await p.onMessage({ type: 'approval', id: c.id, decision: c.decision, feedback: c.decision === 'deny' ? cut(c.feedback, 2000) : undefined })
+    } else if (c.type === 'answer') {
+      await p.onMessage({ type: 'answer', id: c.id, ...(c.dismissed ? { dismissed: true } : { answers: Array.isArray(c.answers) ? c.answers : [] }) })
+    } else if (c.type === 'plan') {
+      // Approved from the browser, the mode is the one the conversation had before planning.
+      await p.onMessage({ type: 'planAnswer', id: c.id, approved: !!c.approved, feedback: c.approved ? undefined : cut(c.feedback, 4000) })
+    } else if (c.type === 'stop') {
+      p.abort?.abort()
+    }
+    this.schedule()
+  }
+
+  /** Ends the sharing: the link stops working for everyone. */
+  stop() {
+    this.active = false
+    clearTimeout(this.retry)
+    clearTimeout(this.pending)
+    this.restorePost?.()
+    try { if (this.ws?.readyState === 1) this.ws.send(JSON.stringify({ type: 'end' })) } catch { /* closing anyway */ }
+    setTimeout(() => { try { this.ws?.close() } catch { /* gone */ } }, 200)
+  }
+}
+
+module.exports = { RemoteLink, snapshot, approvalOf }

package/ext/review.js

@@ -0,0 +1,126 @@
+'use strict'
+// Reviewing a proposed change in the editor, change by change, as Claude Code's diff does:
+// above each change in the proposal, "Keep" and "Undo this change" (which puts the original
+// lines back), and at the top "Accept and apply" / "Reject all" — the same answers as in the
+// panel. The same at the cursor from the context menu. Over 100 changes, whole-file only.
+const vscode = require('vscode')
+const { hunkRanges, applyHunks } = require('./diff')
+
+const MAX_HUNKS = 100
+
+/** The pending approval whose proposal is open in this file, and the panel asking. */
+function findReview(registry, file) {
+  for (const panel of registry.all()) {
+    for (const [id, pending] of panel.approvals || []) {
+      if (pending.review && pending.review === file) return { panel, id, pending }
+    }
+  }
+  return null
+}
+
+/** The changes of the proposal as it is now, against the file as it was. */
+function changes(review, doc) {
+  return hunkRanges(review.pending.request.before ?? '', doc.getText())
+}
+
+function register(context, registry) {
+  const changed = new vscode.EventEmitter()
+  const lenses = {
+    onDidChangeCodeLenses: changed.event,
+    provideCodeLenses(doc) {
+      const review = findReview(registry, doc.uri.fsPath)
+      if (!review) return []
+      const list = changes(review, doc)
+      const top = new vscode.Range(0, 0, 0, 0)
+      const out = [
+        new vscode.CodeLens(top, { title: '$(check) Accept and apply', command: 'aipictury.review.apply', arguments: [doc.uri] }),
+        new vscode.CodeLens(top, { title: '$(close) Reject all', command: 'aipictury.review.reject', arguments: [doc.uri] }),
+      ]
+      if (list.length > MAX_HUNKS) {
+        out.push(new vscode.CodeLens(top, { title: `${list.length} changes — too many to review one by one: accept or reject the whole file`, command: '' }))
+        return out
+      }
+      const kept = review.pending.kept || new Set()
+      for (const h of list) {
+        const at = new vscode.Range(Math.min(h.start, doc.lineCount - 1), 0, Math.min(h.start, doc.lineCount - 1), 0)
+        const sign = signature(review, doc, h)
+        out.push(new vscode.CodeLens(at, kept.has(sign)
+          ? { title: '$(pass-filled) Kept', command: 'aipictury.review.keepChange', arguments: [doc.uri, h.index] }
+          : { title: '$(check) Keep', command: 'aipictury.review.keepChange', arguments: [doc.uri, h.index] }))
+        out.push(new vscode.CodeLens(at, { title: '$(discard) Undo this change', command: 'aipictury.review.undoChange', arguments: [doc.uri, h.index] }))
+      }
+      return out
+    },
+  }
+  const add = (d) => context.subscriptions.push(d)
+  add(vscode.languages.registerCodeLensProvider({ scheme: 'file', pattern: '**/aipictury-review/**' }, lenses))
+  add(vscode.workspace.onDidChangeTextDocument((e) => { if (findReview(registry, e.document.uri.fsPath)) changed.fire() }))
+
+  /** The document and the change a command is about: given, or at the cursor. */
+  const target = (uri, index) => {
+    const editor = vscode.window.activeTextEditor
+    const doc = uri ? vscode.workspace.textDocuments.find((d) => d.uri.fsPath === uri.fsPath) : editor?.document
+    if (!doc) return null
+    const review = findReview(registry, doc.uri.fsPath)
+    if (!review) return null
+    const list = changes(review, doc)
+    let h = Number.isInteger(index) ? list[index] : null
+    if (!h && editor?.document === doc) {
+      const line = editor.selection.active.line
+      h = list.find((x) => line >= x.start && line <= Math.max(x.start, x.end)) || list.find((x) => x.start === line + 1 && x.end < x.start)
+    }
+    return { doc, review, list, h }
+  }
+
+  add(vscode.commands.registerCommand('aipictury.review.undoChange', async (uri, index) => {
+    const t = target(uri, index)
+    if (!t?.h) { vscode.window.showInformationMessage('Put the cursor on a proposed change to undo it.'); return false }
+    const before = t.review.pending.request.before ?? ''
+    const keep = new Set(t.list.map((h) => h.index).filter((i) => i !== t.h.index))
+    const text = applyHunks(before, t.doc.getText(), keep)
+    const edit = new vscode.WorkspaceEdit()
+    edit.replace(t.doc.uri, new vscode.Range(0, 0, t.doc.lineCount, 0), text)
+    await vscode.workspace.applyEdit(edit)
+    changed.fire()
+    return true
+  }))
+  add(vscode.commands.registerCommand('aipictury.review.keepChange', (uri, index) => {
+    const t = target(uri, index)
+    if (!t?.h) return false
+    const kept = (t.review.pending.kept ||= new Set())
+    const sign = signature(t.review, t.doc, t.h)
+    if (kept.has(sign)) kept.delete(sign); else kept.add(sign)
+    changed.fire()
+    return true
+  }))
+  const answer = (decision) => async (uri) => {
+    const doc = uri ? vscode.workspace.textDocuments.find((d) => d.uri.fsPath === uri.fsPath) : vscode.window.activeTextEditor?.document
+    const review = doc && findReview(registry, doc.uri.fsPath)
+    if (!review) return false
+    if (doc.isDirty) await doc.save()
+    review.panel.post({ type: 'approvalClosed', id: review.id })
+    await closeTabsOf(doc.uri.fsPath)
+    await review.panel.onMessage({ type: 'approval', id: review.id, decision })
+    return true
+  }
+  add(vscode.commands.registerCommand('aipictury.review.apply', answer('allow')))
+  add(vscode.commands.registerCommand('aipictury.review.reject', answer('deny')))
+  return { refresh: () => changed.fire() }
+}
+
+/** Closes every tab showing the proposal — its diff, or the file itself — before its copy is
+ *  removed; not whichever editor happens to be active. */
+async function closeTabsOf(file) {
+  const shows = (input) => (input instanceof vscode.TabInputTextDiff && input.modified.fsPath === file)
+    || (input instanceof vscode.TabInputText && input.uri.fsPath === file)
+  const tabs = vscode.window.tabGroups.all.flatMap((g) => g.tabs).filter((t) => shows(t.input))
+  if (tabs.length) await vscode.window.tabGroups.close(tabs, true)
+}
+
+/** A change's identity while the proposal is edited around it: its lines, not its number. */
+function signature(review, doc, h) {
+  const lines = doc.getText().split('\n').slice(h.start, h.end + 1).join('\n')
+  return `${h.start - h.end}:${lines}`
+}
+
+module.exports = { register, findReview, MAX_HUNKS }

package/ext/sandbox.js

@@ -0,0 +1,79 @@
+'use strict'
+// A sandbox for the agent's shell commands: they can write only inside the workspace (and the
+// temp folders), and reach the network only when allowed — macOS's sandbox-exec, Linux's
+// bubblewrap. Like Claude Code's: settings in VS Code or the settings files ("sandbox": {…},
+// Claude Code's own included), commands that are left out of it (docker…), and a way out
+// that always asks the user (outside_sandbox). No VS Code here: tests run it directly.
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { execFileSync } = require('child_process')
+const { commandParts } = require('./permissions')
+
+let found
+/** Which sandbox this machine has: 'macos', 'linux' or null. */
+function available() {
+  if (found !== undefined) return found
+  found = null
+  if (process.platform === 'darwin' && fs.existsSync('/usr/bin/sandbox-exec')) found = 'macos'
+  else if (process.platform === 'linux') {
+    try { execFileSync('bwrap', ['--version'], { stdio: 'ignore', timeout: 3000 }); found = 'linux' } catch { found = null }
+  }
+  return found
+}
+
+/** The sandbox settings: VS Code's (aipictury.sandbox.*) over the settings files' "sandbox". */
+function settings(fromFiles = {}, fromVsCode = {}) {
+  const f = fromFiles || {}
+  const pick = (a, b, fallback) => (a !== undefined ? a : b !== undefined ? b : fallback)
+  return {
+    enabled: !!pick(fromVsCode.enabled, f.enabled, false),
+    allowNetwork: !!pick(fromVsCode.allowNetwork, f.network?.allow ?? f.allowNetwork, false),
+    autoAllow: !!pick(fromVsCode.autoAllow, f.autoAllowBashIfSandboxed, true),
+    excluded: [...new Set([...(f.excludedCommands || []), ...(fromVsCode.excludedCommands || [])])],
+    writable: [...new Set([...(f.writablePaths || []), ...(fromVsCode.writablePaths || [])])],
+  }
+}
+
+/** Is any part of this command one the user left out of the sandbox? */
+function excluded(command, list) {
+  return commandParts(command).some((part) => list.some((p) => part === p || part.startsWith(`${p} `)))
+}
+
+const real = (p) => { try { return fs.realpathSync(p) } catch { return path.resolve(p) } }
+const quote = (p) => `"${String(p).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+
+/** The macOS profile: everything allowed but writes outside the workspace and temp folders,
+ *  and (without allowNetwork) connections beyond this machine. */
+function macProfile({ root, writable = [], network = false }) {
+  const places = [real(root), real(os.tmpdir()), '/private/tmp', '/private/var/folders', ...writable.map((w) => real(w.replace(/^~/, os.homedir())))]
+  return ['(version 1)', '(allow default)', '(deny file-write*)',
+    `(allow file-write* ${places.map((p) => `(subpath ${quote(p)})`).join(' ')} (subpath "/dev"))`,
+    ...(network ? [] : ['(deny network-outbound)', '(allow network-outbound (remote unix-socket))', '(allow network-outbound (remote ip "localhost:*"))']),
+  ].join('\n')
+}
+
+/** How to start `script` sandboxed: { file, args }, or null when this machine has no sandbox. */
+function wrap(shell, script, { root, writable = [], network = false } = {}) {
+  const kind = available()
+  if (kind === 'macos') return { file: '/usr/bin/sandbox-exec', args: ['-p', macProfile({ root, writable, network }), shell, '-c', script] }
+  if (kind === 'linux') {
+    const binds = [real(root), real(os.tmpdir()), ...writable.map((w) => real(w.replace(/^~/, os.homedir())))]
+      .flatMap((p) => ['--bind', p, p])
+    return { file: 'bwrap', args: ['--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', ...binds,
+      ...(network ? [] : ['--unshare-net']), '--die-with-parent', '--chdir', real(root), '--', shell, '-c', script] }
+  }
+  return null
+}
+
+/** What a sandbox refusal looks like in a command's output. */
+const REFUSED = /Operation not permitted|Read-only file system|sandbox-exec: |deny\(\d\)|Could not resolve host|Network is unreachable|nodename nor servname/i
+
+/** A note for the model when the sandbox stopped a command. */
+function note(output, { network }) {
+  if (!REFUSED.test(String(output || ''))) return ''
+  return `\n[The sandbox may have stopped this: commands can write only inside the workspace${network ? '' : ' and cannot reach the network'}. `
+    + 'If that is needed, run it again with outside_sandbox: true — the user will be asked first.]'
+}
+
+module.exports = { available, settings, excluded, macProfile, wrap, note, REFUSED }

package/ext/scheduler.js

@@ -0,0 +1,87 @@
+'use strict'
+// Prompts on a schedule, for one conversation: a cron expression ("*/15 9-17 * * 1-5") or an
+// interval ("10m", "2h"), recurring or once — /loop, the agent's cron tools and its wake-ups.
+// Pure: the time is given, so the tests use a clock of their own.
+const MINUTE = 60_000
+
+/** "10m", "2h", "90s", "every 5 minutes", "1d" → milliseconds, or null. */
+function interval(text) {
+  const m = /^(?:every\s+)?(\d+(?:\.\d+)?)\s*(s|sec|secs|seconds?|m|min|mins|minutes?|h|hr|hrs|hours?|d|days?)$/i.exec(String(text || '').trim())
+  if (!m) return null
+  const n = Number(m[1])
+  const unit = m[2][0].toLowerCase()
+  const ms = n * { s: 1000, m: MINUTE, h: 60 * MINUTE, d: 24 * 60 * MINUTE }[unit]
+  return ms >= MINUTE ? ms : null                    // at most once a minute
+}
+
+/** One cron field ("*", "5", "1-5", "*\/15", "1,3,5", "9-17/2") → the set of values it allows. */
+function field(text, min, max) {
+  const out = new Set()
+  for (const part of String(text).split(',')) {
+    const m = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/.exec(part.trim())
+    if (!m) throw new Error(`"${part}" is not a cron field`)
+    let [lo, hi] = m[1] === '*' ? [min, max] : m[1].split('-').map(Number)
+    if (hi === undefined) hi = m[2] ? max : lo
+    const step = Number(m[2] || 1)
+    if (lo < min || hi > max || lo > hi || step < 1) throw new Error(`"${part}" is outside ${min}-${max}`)
+    for (let v = lo; v <= hi; v += step) out.add(v)
+  }
+  return out
+}
+
+/** A 5-field cron expression (minute hour day-of-month month day-of-week), in local time. */
+function cron(text) {
+  const parts = String(text || '').trim().split(/\s+/)
+  if (parts.length !== 5) throw new Error('a cron expression has 5 fields: minute hour day month weekday')
+  const [mi, h, dom, mo, dow] = parts
+  const spec = { minutes: field(mi, 0, 59), hours: field(h, 0, 23), days: field(dom, 1, 31), months: field(mo, 1, 12),
+    weekdays: new Set([...field(dow, 0, 7)].map((d) => d % 7)), anyDay: dom === '*', anyWeekday: dow === '*' }
+  return spec
+}
+
+/** The first time after `after` (ms) that a cron spec allows, or null within a year. */
+function nextCron(spec, after) {
+  const t = new Date(after)
+  t.setSeconds(0, 0)
+  t.setMinutes(t.getMinutes() + 1)
+  for (let i = 0; i < 366 * 24 * 60; i += 1) {
+    // Day of month and day of week: either matches when both are restricted, as cron does.
+    const dayOk = spec.anyDay && spec.anyWeekday ? true
+      : spec.anyDay ? spec.weekdays.has(t.getDay()) : spec.anyWeekday ? spec.days.has(t.getDate())
+        : spec.days.has(t.getDate()) || spec.weekdays.has(t.getDay())
+    if (spec.months.has(t.getMonth() + 1) && dayOk && spec.hours.has(t.getHours()) && spec.minutes.has(t.getMinutes())) return t.getTime()
+    t.setMinutes(t.getMinutes() + 1)
+  }
+  return null
+}
+
+/** A new job: { id, prompt, schedule, recurring, next }. `schedule` is an interval or a cron line. */
+function job(jobs, { schedule, prompt, recurring = true, now = Date.now(), kind = 'cron' }) {
+  const text = String(prompt || '').trim()
+  if (!text) throw new Error('a scheduled prompt cannot be empty')
+  if (jobs.length >= 20) throw new Error('at most 20 scheduled prompts in a conversation — delete some first')
+  const every = interval(schedule)
+  const spec = every ? null : cron(schedule)
+  const next = every ? now + every : nextCron(spec, now)
+  if (!next) throw new Error(`"${schedule}" never comes in the next year`)
+  const id = `job_${Math.max(0, ...jobs.map((j) => Number(String(j.id).replace('job_', '')) || 0)) + 1}`
+  return { id, prompt: text, schedule: String(schedule).trim(), recurring: !!recurring, next, kind, created: now }
+}
+
+/** The jobs due at `now`, and the list as it is after them (recurring ones moved on). */
+function due(jobs, now = Date.now()) {
+  const ready = jobs.filter((j) => j.next <= now)
+  const rest = jobs.filter((j) => j.next > now || j.recurring).map((j) => {
+    if (j.next > now) return j
+    const every = interval(j.schedule)
+    return { ...j, next: every ? Math.max(now, j.next) + every - ((Math.max(now, j.next) - j.next) % every) : nextCron(cron(j.schedule), now) }
+  }).filter((j) => j.next)
+  return { ready, jobs: rest }
+}
+
+function describe(j, now = Date.now()) {
+  const mins = Math.max(0, Math.round((j.next - now) / MINUTE))
+  return `${j.id} — ${j.recurring ? `every ${j.schedule}` : `once (${j.schedule})`}, next in ${mins < 60 ? `${mins} min` : `${Math.round(mins / 60)} h`}: ${j.prompt.slice(0, 120)}`
+}
+
+module.exports = { interval, cron, nextCron, job, due, describe }