@sciilo.ai/codex-sidecar 0.1.0

package/src/codex-app-server.js

@@ -0,0 +1,125 @@
+import { EventEmitter } from 'node:events'
+import { spawn } from 'node:child_process'
+import { createInterface } from 'node:readline'
+import { codexInvocation } from './codex-cli.js'
+
+export class CodexAppServer extends EventEmitter {
+  constructor({ command, cwd, spawnProcess = spawn } = {}) {
+    super()
+    this.invocation = codexInvocation(command)
+    this.cwd = cwd
+    this.spawnProcess = spawnProcess
+    this.nextId = 1
+    this.pending = new Map()
+    this.child = null
+  }
+
+  async start() {
+    if (this.child) return
+    const child = this.spawnProcess(
+      this.invocation.command,
+      [...this.invocation.prefixArgs, 'app-server'],
+      {
+      cwd: this.cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: process.env,
+      },
+    )
+    this.child = child
+    child.once('error', error => this.failAll(error))
+    child.once('exit', (code, signal) => {
+      const error = new Error(`Codex App Server stopped (${signal || code}).`)
+      this.child = null
+      this.failAll(error)
+      this.emit('exit', error)
+    })
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', chunk => this.emit('log', chunk.trimEnd()))
+    createInterface({ input: child.stdout }).on('line', line => this.receiveLine(line))
+
+    await this.request('initialize', {
+      clientInfo: {
+        name: 'sciilo-sidecar',
+        title: 'Sciilo Codex Sidecar',
+        version: '0.1.0',
+      },
+      capabilities: {
+        experimentalApi: true,
+        requestAttestation: false,
+      },
+    })
+    this.notify('initialized')
+    const account = await this.request('account/read', { refreshToken: false })
+    if (account?.requiresOpenaiAuth && !account?.account) {
+      throw new Error('Codex is not authenticated. Run `sciilo-sidecar setup`.')
+    }
+  }
+
+  request(method, params) {
+    if (!this.child?.stdin?.writable) {
+      return Promise.reject(new Error('Codex App Server is unavailable.'))
+    }
+    const id = this.nextId++
+    return new Promise((resolve, reject) => {
+      this.pending.set(String(id), { resolve, reject, method })
+      this.write({ method, id, params })
+    })
+  }
+
+  notify(method, params) {
+    this.write(params === undefined ? { method } : { method, params })
+  }
+
+  respond(id, result) {
+    this.write({ id, result })
+  }
+
+  respondError(id, message, code = -32603) {
+    this.write({ id, error: { code, message } })
+  }
+
+  write(frame) {
+    this.child?.stdin?.write(`${JSON.stringify(frame)}\n`)
+  }
+
+  receiveLine(line) {
+    if (!line.trim()) return
+    let frame
+    try {
+      frame = JSON.parse(line)
+    } catch {
+      this.emit('log', `Ignored non-JSON Codex frame: ${line}`)
+      return
+    }
+    if (frame.id !== undefined && !frame.method) {
+      const pending = this.pending.get(String(frame.id))
+      if (!pending) return
+      this.pending.delete(String(frame.id))
+      if (frame.error) {
+        const error = new Error(frame.error.message || `${pending.method} failed`)
+        error.code = frame.error.code
+        pending.reject(error)
+      } else {
+        pending.resolve(frame.result)
+      }
+      return
+    }
+    if (frame.method && frame.id !== undefined) {
+      this.emit('request', frame)
+      return
+    }
+    if (frame.method) this.emit('notification', frame)
+  }
+
+  stop() {
+    const child = this.child
+    this.child = null
+    if (child && !child.killed) child.kill('SIGTERM')
+    this.failAll(new Error('Codex App Server stopped.'))
+  }
+
+  failAll(error) {
+    for (const pending of this.pending.values()) pending.reject(error)
+    this.pending.clear()
+  }
+}

package/src/codex-cli.js

@@ -0,0 +1,37 @@
+import { spawnSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+export function bundledCodexEntrypoint(resolvePackage = require.resolve) {
+  return resolvePackage('@openai/codex/bin/codex.js')
+}
+
+export function codexInvocation(configuredCommand, resolvePackage) {
+  if (configuredCommand) {
+    return {
+      command: configuredCommand,
+      prefixArgs: [],
+      source: 'configured',
+    }
+  }
+  return {
+    command: process.execPath,
+    prefixArgs: [bundledCodexEntrypoint(resolvePackage)],
+    source: 'bundled',
+  }
+}
+
+export function runCodexSync(
+  configuredCommand,
+  args,
+  options,
+  spawnProcess = spawnSync,
+) {
+  const invocation = codexInvocation(configuredCommand)
+  return spawnProcess(
+    invocation.command,
+    [...invocation.prefixArgs, ...args],
+    options,
+  )
+}

package/src/config.js

@@ -0,0 +1,87 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { homedir } from 'node:os'
+
+export const DEFAULT_CODEX_MODEL = 'gpt-5.6-sol'
+
+/**
+ * Pinned rather than inherited.
+ *
+ * A thread started without this setting takes whatever `model_reasoning_effort`
+ * the machine's `~/.codex/config.toml` happens to hold — a personal CLI
+ * preference, set for an entirely different purpose. On a machine configured
+ * for `xhigh`, every answer paid for maximum reasoning before its first token,
+ * and the product behaved differently from one computer to the next for a
+ * reason no one could see from here.
+ */
+export const DEFAULT_REASONING_EFFORT = 'medium'
+
+export const defaultConfigPath = () => process.env.SCIILO_SIDECAR_CONFIG
+  || join(homedir(), '.config', 'sciilo-sidecar', 'config.json')
+
+export function resolveWorkspace(explicit) {
+  return resolve(explicit || process.cwd())
+}
+
+export async function loadConfig(path = defaultConfigPath()) {
+
+  let raw
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+  const config = JSON.parse(raw)
+  validateConfig(config)
+  return normalizeConfig(config)
+}
+
+export async function saveConfig(config, path = defaultConfigPath()) {
+  validateConfig(config)
+  const normalized = normalizeConfig(config)
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+  await writeFile(path, `${JSON.stringify(normalized, null, 2)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600,
+  })
+  await chmod(path, 0o600)
+  return normalized
+}
+
+export function normalizeConfig(config) {
+  const configuredModel = config.model === 'gtp-sol'
+    ? DEFAULT_CODEX_MODEL
+    : config.model
+  const configuredCommand = typeof config.codexCommand === 'string'
+    ? config.codexCommand.trim()
+    : ''
+  return {
+    appUrl: config.appUrl.replace(/\/+$/, ''),
+    connectionKey: config.connectionKey.trim(),
+    codexCommand: configuredCommand && configuredCommand !== 'codex'
+      ? configuredCommand
+      : null,
+    model: configuredModel || DEFAULT_CODEX_MODEL,
+    modelProvider: config.modelProvider || null,
+    reasoningEffort: (typeof config.reasoningEffort === 'string'
+      && config.reasoningEffort.trim()) || DEFAULT_REASONING_EFFORT,
+  }
+}
+
+export function validateConfig(config) {
+  if (!config || typeof config !== 'object') {
+    throw new Error('Sidecar configuration is missing.')
+  }
+  if (!/^https?:\/\//.test(config.appUrl || '')) {
+    throw new Error('appUrl must start with http:// or https://.')
+  }
+  const appUrl = new URL(config.appUrl)
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(appUrl.hostname)
+  if (appUrl.protocol !== 'https:' && !loopback) {
+    throw new Error('HTTPS is required outside the local machine.')
+  }
+  if (!/^sc_[0-9a-f-]{36}\.[A-Za-z0-9_-]{40,}$/.test(config.connectionKey || '')) {
+    throw new Error('The sidecar connection key is invalid.')
+  }
+}

package/src/document-seal.js

@@ -0,0 +1,195 @@
+import { fieldContext, openField, sealField } from './vault.js'
+
+export const MARKER = 'sciilo:sealed:v1:'
+
+const TOKEN = /sciilo:sealed:v1:([0-9a-fA-F-]{36}):([a-z_]+):([A-Za-z0-9+/]+={0,2})/g
+
+export function isSealed(value) {
+  return typeof value === 'string' && value.startsWith(MARKER)
+}
+
+function contextOf(documentId, field) {
+  return fieldContext({ documentId, field })
+}
+
+export async function sealValue(key, documentId, field, plaintext) {
+  const sealed = await sealField(key, String(plaintext), contextOf(documentId, field))
+  return `${MARKER}${documentId}:${field}:${sealed}`
+}
+
+export async function openValue(key, token) {
+  const parts = TOKEN.exec(token)
+  TOKEN.lastIndex = 0
+  if (!parts) throw new Error('Not a sealed field.')
+  const [, documentId, field, payload] = parts
+  return openField(key, payload, contextOf(documentId, field))
+}
+
+/**
+ * Opens every sealed token embedded in a piece of text.
+ *
+ * <p>The replacement goes through a FUNCTION, never a string. Passing the
+ * plaintext as the replacement made `$&`, `` $` ``, `$'` and `$1` inside it
+ * expand as substitution patterns: a decrypted note containing `100 $&` used to
+ * paste the ciphertext token back into what the agent reads. The content is
+ * data, and this is the only way to say so.</p>
+ *
+ * <p>Tokens are opened once each and substituted in a single pass. Replacing
+ * them one at a time re-scanned the whole text per token, which on a board
+ * carrying several sealed fields is quadratic for no reason.</p>
+ */
+export async function openText(key, text) {
+  if (typeof text !== 'string' || !text.includes(MARKER)) return text
+  const tokens = [...new Set(text.match(TOKEN) || [])]
+  if (!tokens.length) return text
+
+  const clear = new Map()
+  await Promise.all(tokens.map(async token => {
+    try {
+      clear.set(token, await openValue(key, token))
+    } catch {
+      // Left as it stands: a token that refuses to open is better shown
+      // unreadable than replaced by nothing, which would read as empty.
+    }
+  }))
+  return text.replace(TOKEN, token => clear.get(token) ?? token)
+}
+
+export function diagramKind(language, source) {
+  const lang = String(language || '').trim().toLowerCase()
+  const lower = String(source || '').trim().toLowerCase()
+
+  if (lang === 'plantuml') {
+    if (/\b(?:class|interface|enum|annotation|entity|struct)\b/.test(lower)) {
+      return 'Class diagram'
+    }
+    if (lower.includes('[*]') || /\bstate\s+[\w"]/.test(lower)) return 'State diagram'
+    return 'Sequence diagram'
+  }
+  if (lang !== 'mermaid') return 'Diagram'
+
+  if (lower.includes('%% sciilo:product-vision')) return 'Product Vision'
+  if (/^erdiagram\b/.test(lower)) return 'Data model'
+  if (/^classdiagram\b/.test(lower)) return 'Class diagram'
+  if (/^sequencediagram\b/.test(lower)) return 'Sequence diagram'
+  if (/^statediagram(?:-v2)?\b/.test(lower)) return 'State diagram'
+  if (/^mindmap\b/.test(lower)) return 'Mind map'
+  if (/^journey\b/.test(lower)) return 'User journey'
+  if (/^c4(?:context|container|component|dynamic|deployment)\b/.test(lower)) return 'C4 architecture'
+  if (/^(?:flowchart|graph)\b/.test(lower)) return 'Flowchart'
+  return 'Mermaid diagram'
+}
+
+/** PlantUML announces itself; everything else here is Mermaid. */
+export function guessLanguage(source) {
+  return /^\s*@startuml/i.test(String(source || '')) ? 'plantuml' : 'mermaid'
+}
+
+export function excerptOf(source) {
+  const plain = String(source || '')
+    .replace(/^\s{0,3}#{1,6}\s+/gm, '')
+    .replace(/\[([^\]]+)]\([^)]+\)/g, '$1')
+    .replace(/[*_`>|]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return plain.length > 180 ? `${plain.slice(0, 177).trimEnd()}...` : plain
+}
+
+const VISION_MARKER = '%% sciilo:product-vision'
+
+const VISION_SECTIONS = [
+  ['emotions', 'Desired momentum'],
+  ['problem', 'Problem'],
+  ['users', 'Users'],
+  ['value', 'Value proposition'],
+  ['capabilities', 'Main capabilities'],
+  ['journeys', 'Key journeys'],
+  ['unknowns', 'Unknowns to confirm'],
+]
+
+function visionEscaped(value) {
+  return String(value ?? '').replace(/\r/g, ' ').replace(/\n/g, ' ').replace(/"/g, '#quot;')
+}
+
+function visionBranch(lines, key, label, items) {
+  lines.push(`    ${key}["${visionEscaped(label)}"]`)
+  items.forEach((item, index) => {
+    lines.push(`      ${key}_${index + 1}["${visionEscaped(item)}"]`)
+  })
+}
+
+function visionList(raw) {
+  if (!Array.isArray(raw)) return []
+  return raw.map(value => String(value ?? '').trim()).filter(Boolean).slice(0, 6)
+}
+
+export function productVisionSource(args = {}) {
+  const lines = [VISION_MARKER, 'mindmap', `  product(("${visionEscaped(args.product)}"))`]
+  visionBranch(lines, 'vision', 'Vision', [String(args.vision ?? '')])
+  for (const [key, label] of VISION_SECTIONS) {
+    visionBranch(lines, key, label, visionList(args[key]))
+  }
+  return lines.join('\n')
+}
+
+const CONTENT_TOOLS = {
+  create_diagram: { fields: ['source'], creates: true, derive: deriveDiagram },
+  update_diagram: { fields: ['source'], idFrom: 'document_id', derive: deriveDiagram },
+  create_markdown_board: { fields: ['source', 'excerpt'], creates: true, derive: deriveMarkdown },
+  update_markdown_board: { fields: ['source', 'excerpt'], idFrom: 'document_id', derive: deriveMarkdown },
+  create_product_vision: {
+    fields: ['source'],
+    creates: true,
+    derive: deriveVision,
+    strip: ['product', 'vision', ...VISION_SECTIONS.map(([key]) => key)],
+  },
+
+  add_note: { fields: ['content'], idFrom: 'document_id' },
+  update_note: { fields: ['content'], idFrom: 'document_id' },
+}
+
+function deriveDiagram(args) {
+  const lang = args.lang || guessLanguage(args.source)
+  return { kind: diagramKind(lang, args.source) }
+}
+
+function deriveMarkdown(args) {
+  return { excerpt: excerptOf(args.source) }
+}
+
+function deriveVision(args) {
+  return { source: productVisionSource(args), lang: 'mermaid' }
+}
+
+/**
+ * Seals the content-bearing arguments of a tool call.
+ *
+ * Returns the arguments unchanged when there is no key, when the tool carries
+ * no content, or when there is nothing to seal. Refusing to write would be a
+ * worse failure than writing in clear: the user would lose the work, and the
+ * database guard already reports anything readable that reaches storage.
+ */
+export async function sealArguments(key, tool, args) {
+  const spec = CONTENT_TOOLS[tool]
+  if (!key || !spec || !args || typeof args !== 'object') return args
+
+  const sealedArgs = { ...args, ...(spec.derive ? spec.derive(args) : {}) }
+  const documentId = spec.creates
+    ? (sealedArgs.documentId = randomId())
+    : sealedArgs[spec.idFrom]
+  if (!documentId) return args
+
+  for (const field of spec.fields) {
+    const value = sealedArgs[field]
+    if (typeof value !== 'string' || !value || isSealed(value)) continue
+    sealedArgs[field] = await sealValue(key, documentId, field, value)
+  }
+  for (const field of spec.strip || []) {
+    delete sealedArgs[field]
+  }
+  return sealedArgs
+}
+
+function randomId() {
+  return crypto.randomUUID()
+}