freddie 0.0.41

package/src/gateway/platforms/mattermost.js

@@ -0,0 +1,29 @@
+import express from 'express'
+import { EventEmitter } from 'node:events'
+
+export class MattermostAdapter extends EventEmitter {
+    constructor(opts = {}) {
+        super()
+        this.platform = 'mattermost'
+        this.url = opts.url || process.env.MATTERMOST_URL
+        this.token = opts.token || process.env.MATTERMOST_TOKEN
+        this.port = opts.port || 0
+        this._server = null
+    }
+    getRequiredEnv() { return ['MATTERMOST_URL', 'MATTERMOST_TOKEN'] }
+    async start() {
+        if (!this.url || !this.token) throw new Error('MattermostAdapter: MATTERMOST_URL + MATTERMOST_TOKEN required')
+        const app = express()
+        app.use(express.urlencoded({ extended: true }))
+        app.post('/hook', (req, res) => {
+            this.emit('message', { from: req.body.channel_id, text: req.body.text || '', user: req.body.user_id, raw: req.body })
+            res.json({})
+        })
+        await new Promise(r => { this._server = app.listen(this.port, () => r()) })
+        this.port = this._server.address().port
+    }
+    async stop() { if (this._server) await new Promise(r => this._server.close(() => r())) }
+    async send(reply) {
+        return fetch(`${this.url}/api/v4/posts`, { method: 'POST', headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' }, body: JSON.stringify({ channel_id: reply.to, message: reply.text }) }).then(r => r.json())
+    }
+}

package/src/gateway/platforms/qqbot.js

@@ -0,0 +1,32 @@
+import express from 'express'
+import { EventEmitter } from 'node:events'
+
+export class QqbotAdapter extends EventEmitter {
+    constructor(opts = {}) {
+        super()
+        this.platform = 'qqbot'
+        this.token = opts.token || process.env.QQBOT_TOKEN
+        this.port = opts.port || 0
+        this.api = opts.api || "https://api.sgroup.qq.com/channels/messages"
+        this._server = null
+    }
+    getRequiredEnv() { return ["QQBOT_TOKEN"] }
+    async start() {
+        if (!this.token) throw new Error('QqbotAdapter: ' + this.getRequiredEnv().join(', ') + ' required')
+        const app = express()
+        app.use(express.json())
+        app.post('/webhook', (req, res) => {
+            const text = req.body?.text || req.body?.message?.text || req.body?.content || ''
+            const from = req.body?.from || req.body?.user_id || req.body?.sender_id || ''
+            this.emit('message', { from: String(from), text, raw: req.body })
+            res.json({ ok: true })
+        })
+        await new Promise(r => { this._server = app.listen(this.port, () => r()) })
+        this.port = this._server.address().port
+    }
+    async stop() { if (this._server) await new Promise(r => this._server.close(() => r())) }
+    async send(reply) {
+        if (!this.token) throw new Error('QqbotAdapter: token required')
+        return fetch(this.api, { method: 'POST', headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' }, body: JSON.stringify({ to: reply.to, text: reply.text }) }).then(r => r.json())
+    }
+}

package/src/gateway/platforms/signal.js

@@ -0,0 +1,33 @@
+import { EventEmitter } from 'node:events'
+
+export class SignalAdapter extends EventEmitter {
+    constructor(opts = {}) {
+        super()
+        this.platform = 'signal'
+        this.api = opts.api || process.env.SIGNAL_CLI_URL || 'http://127.0.0.1:8080'
+        this.number = opts.number || process.env.SIGNAL_NUMBER
+        this._running = false
+    }
+    getRequiredEnv() { return ['SIGNAL_CLI_URL', 'SIGNAL_NUMBER'] }
+    async start() {
+        if (!this.number) throw new Error('SignalAdapter: SIGNAL_NUMBER required')
+        this._running = true
+        this._loop()
+    }
+    async stop() { this._running = false }
+    async _loop() {
+        while (this._running) {
+            try {
+                const res = await fetch(`${this.api}/v1/receive/${this.number}`)
+                const items = await res.json()
+                for (const it of items) {
+                    const msg = it?.envelope?.dataMessage
+                    if (msg) this.emit('message', { from: it.envelope.source, text: msg.message || '', raw: it })
+                }
+            } catch (e) { await new Promise(r => setTimeout(r, 2000)) }
+        }
+    }
+    async send(reply) {
+        return fetch(`${this.api}/v2/send`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ number: this.number, recipients: [reply.to], message: reply.text }) }).then(r => r.json())
+    }
+}

package/src/gateway/platforms/slack.js

@@ -0,0 +1,34 @@
+import express from 'express'
+import { EventEmitter } from 'node:events'
+
+export class SlackAdapter extends EventEmitter {
+    constructor(opts = {}) {
+        super()
+        this.platform = 'slack'
+        this.token = opts.token || process.env.SLACK_BOT_TOKEN
+        this.signingSecret = opts.signingSecret || process.env.SLACK_SIGNING_SECRET
+        this.port = opts.port || 0
+        this.path = opts.path || '/slack/events'
+        this.api = opts.api || 'https://slack.com/api'
+        this._server = null
+    }
+    getRequiredEnv() { return ['SLACK_BOT_TOKEN', 'SLACK_SIGNING_SECRET'] }
+    async start() {
+        if (!this.token) throw new Error('SlackAdapter: SLACK_BOT_TOKEN required')
+        const app = express()
+        app.use(express.json())
+        app.post(this.path, (req, res) => {
+            if (req.body?.type === 'url_verification') return res.json({ challenge: req.body.challenge })
+            const ev = req.body?.event
+            if (ev?.type === 'message' && !ev.bot_id) this.emit('message', { from: ev.channel, text: ev.text || '', user: ev.user, raw: req.body })
+            res.json({ ok: true })
+        })
+        await new Promise(r => { this._server = app.listen(this.port, () => r()) })
+        this.port = this._server.address().port
+    }
+    async stop() { if (this._server) await new Promise(r => this._server.close(() => r())) }
+    async send(reply) {
+        if (!this.token) throw new Error('SlackAdapter: token required')
+        return fetch(`${this.api}/chat.postMessage`, { method: 'POST', headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' }, body: JSON.stringify({ channel: reply.to, text: reply.text }) }).then(r => r.json())
+    }
+}

package/src/gateway/platforms/sms.js

@@ -0,0 +1,34 @@
+import express from 'express'
+import { EventEmitter } from 'node:events'
+
+export class SmsAdapter extends EventEmitter {
+    constructor(opts = {}) {
+        super()
+        this.platform = 'sms'
+        this.sid = opts.sid || process.env.TWILIO_SID
+        this.token = opts.token || process.env.TWILIO_TOKEN
+        this.from = opts.from || process.env.TWILIO_FROM
+        this.port = opts.port || 0
+        this._server = null
+    }
+    getRequiredEnv() { return ['TWILIO_SID', 'TWILIO_TOKEN', 'TWILIO_FROM'] }
+    async start() {
+        if (!this.sid || !this.token || !this.from) throw new Error('SmsAdapter: TWILIO_SID/TOKEN/FROM required')
+        const app = express()
+        app.use(express.urlencoded({ extended: true }))
+        app.post('/sms', (req, res) => {
+            this.emit('message', { from: req.body.From, text: req.body.Body || '', raw: req.body })
+            res.set('content-type', 'text/xml')
+            res.send('<Response/>')
+        })
+        await new Promise(r => { this._server = app.listen(this.port, () => r()) })
+        this.port = this._server.address().port
+    }
+    async stop() { if (this._server) await new Promise(r => this._server.close(() => r())) }
+    async send(reply) {
+        const url = `https://api.twilio.com/2010-04-01/Accounts/${this.sid}/Messages.json`
+        const body = new URLSearchParams({ To: reply.to, From: this.from, Body: reply.text }).toString()
+        const auth = 'Basic ' + Buffer.from(`${this.sid}:${this.token}`).toString('base64')
+        return fetch(url, { method: 'POST', headers: { authorization: auth, 'content-type': 'application/x-www-form-urlencoded' }, body }).then(r => r.json())
+    }
+}

package/src/gateway/platforms/telegram.js

@@ -0,0 +1,38 @@
+import { EventEmitter } from 'node:events'
+
+export class TelegramAdapter extends EventEmitter {
+    constructor(opts = {}) {
+        super()
+        this.platform = 'telegram'
+        this.token = opts.token || process.env.TELEGRAM_BOT_TOKEN
+        this.api = opts.api || 'https://api.telegram.org'
+        this.offset = 0
+        this._running = false
+        this._poll = null
+    }
+    getRequiredEnv() { return ['TELEGRAM_BOT_TOKEN'] }
+    async start() {
+        if (!this.token) throw new Error('TelegramAdapter: TELEGRAM_BOT_TOKEN required')
+        this._running = true
+        this._loop()
+    }
+    async stop() { this._running = false; if (this._poll) clearTimeout(this._poll) }
+    async _loop() {
+        while (this._running) {
+            try {
+                const url = `${this.api}/bot${this.token}/getUpdates?timeout=25&offset=${this.offset + 1}`
+                const res = await fetch(url)
+                const data = await res.json()
+                if (data.ok) for (const u of data.result) {
+                    this.offset = Math.max(this.offset, u.update_id)
+                    if (u.message) this.emit('message', { from: String(u.message.from?.id || ''), text: u.message.text || '', raw: u })
+                }
+            } catch (e) { await new Promise(r => setTimeout(r, 5000)) }
+        }
+    }
+    async send(reply) {
+        if (!this.token) throw new Error('TelegramAdapter: token required')
+        const url = `${this.api}/bot${this.token}/sendMessage`
+        return fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ chat_id: reply.to, text: reply.text }) }).then(r => r.json())
+    }
+}

package/src/gateway/platforms/telegram_network.js

@@ -0,0 +1,17 @@
+export function tgFloodWait(error) {
+    const m = String(error?.message || '').match(/FLOOD_WAIT_(\d+)/)
+    return m ? Number(m[1]) * 1000 : null
+}
+export async function tgWithRetry(fn, { attempts = 3 } = {}) {
+    let last
+    for (let i = 0; i < attempts; i++) {
+        try { return await fn() } catch (e) {
+            last = e
+            const wait = tgFloodWait(e)
+            if (wait != null) await new Promise(r => setTimeout(r, wait + 100))
+            else if (i < attempts - 1) await new Promise(r => setTimeout(r, 500 * (i + 1)))
+        }
+    }
+    throw last
+}
+export function withProxy(fetchOpts, proxy) { return proxy ? { ...fetchOpts, proxy } : fetchOpts }

package/src/gateway/platforms/webhook.js

@@ -0,0 +1,19 @@
+import express from 'express'
+import { EventEmitter } from 'node:events'
+
+export class WebhookAdapter extends EventEmitter {
+    constructor({ port = 0, path = '/webhook' } = {}) { super(); this.port = port; this.path = path; this._server = null; this.outbox = [] }
+    async start() {
+        const app = express()
+        app.use(express.json())
+        app.post(this.path, (req, res) => {
+            const m = { from: req.body?.from || 'webhook', text: req.body?.text || '', raw: req.body }
+            this.emit('message', m)
+            res.json({ ok: true })
+        })
+        await new Promise(resolve => { this._server = app.listen(this.port, () => resolve()) })
+        this.port = this._server.address().port
+    }
+    async stop() { if (this._server) await new Promise(r => this._server.close(() => r())) }
+    async send(reply) { this.outbox.push(reply) }
+}

package/src/gateway/platforms/wecom.js

@@ -0,0 +1,32 @@
+import express from 'express'
+import { EventEmitter } from 'node:events'
+
+export class WecomAdapter extends EventEmitter {
+    constructor(opts = {}) {
+        super()
+        this.platform = 'wecom'
+        this.token = opts.token || process.env.WECOM_WEBHOOK_KEY
+        this.port = opts.port || 0
+        this.api = opts.api || "https://qyapi.weixin.qq.com/cgi-bin/webhook/send"
+        this._server = null
+    }
+    getRequiredEnv() { return ["WECOM_WEBHOOK_KEY"] }
+    async start() {
+        if (!this.token) throw new Error('WecomAdapter: ' + this.getRequiredEnv().join(', ') + ' required')
+        const app = express()
+        app.use(express.json())
+        app.post('/webhook', (req, res) => {
+            const text = req.body?.text || req.body?.message?.text || req.body?.content || ''
+            const from = req.body?.from || req.body?.user_id || req.body?.sender_id || ''
+            this.emit('message', { from: String(from), text, raw: req.body })
+            res.json({ ok: true })
+        })
+        await new Promise(r => { this._server = app.listen(this.port, () => r()) })
+        this.port = this._server.address().port
+    }
+    async stop() { if (this._server) await new Promise(r => this._server.close(() => r())) }
+    async send(reply) {
+        if (!this.token) throw new Error('WecomAdapter: token required')
+        return fetch(this.api, { method: 'POST', headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' }, body: JSON.stringify({ to: reply.to, text: reply.text }) }).then(r => r.json())
+    }
+}

package/src/gateway/platforms/wecom_callback.js

@@ -0,0 +1,15 @@
+import express from 'express'
+import { EventEmitter } from 'node:events'
+export class WecomCallbackAdapter extends EventEmitter {
+    constructor(opts = {}) { super(); this.platform = 'wecom_callback'; this.token = opts.token || process.env.WECOM_CALLBACK_TOKEN; this.aesKey = opts.aesKey || process.env.WECOM_ENCODING_AES_KEY; this.port = opts.port || 0 }
+    getRequiredEnv() { return ['WECOM_CALLBACK_TOKEN'] }
+    async start() {
+        if (!this.token) throw new Error('WECOM_CALLBACK_TOKEN required')
+        const app = express(); app.use(express.text({ type: '*/*' }))
+        app.post('/wecom/callback', (req, res) => { this.emit('message', { from: 'wecom', text: req.body || '', raw: req.body }); res.send('') })
+        this._server = await new Promise(r => { const s = app.listen(this.port, () => r(s)) })
+        this.port = this._server.address().port
+    }
+    async stop() { if (this._server) await new Promise(r => this._server.close(() => r())) }
+    async send() { return { error: 'wecom_callback is receive-only; use wecom adapter for outbound' } }
+}

package/src/gateway/platforms/wecom_crypto.js

@@ -0,0 +1,16 @@
+import crypto from 'node:crypto'
+export function sha1(...parts) { return crypto.createHash('sha1').update(parts.sort().join('')).digest('hex') }
+export function verifyMsgSignature({ token, timestamp, nonce, encrypt, signature }) {
+    return sha1(token, timestamp, nonce, encrypt) === signature
+}
+export function decryptMsg(encryptedB64, encodingAesKey) {
+    const aesKey = Buffer.from(encodingAesKey + '=', 'base64')
+    const iv = aesKey.slice(0, 16)
+    const decipher = crypto.createDecipheriv('aes-256-cbc', aesKey, iv)
+    decipher.setAutoPadding(false)
+    const decrypted = Buffer.concat([decipher.update(Buffer.from(encryptedB64, 'base64')), decipher.final()])
+    const padLen = decrypted[decrypted.length - 1]
+    const trimmed = decrypted.slice(16, decrypted.length - padLen)
+    const xmlLen = trimmed.readUInt32BE(0)
+    return { xml: trimmed.slice(4, 4 + xmlLen).toString('utf8'), corpId: trimmed.slice(4 + xmlLen).toString('utf8') }
+}

package/src/gateway/platforms/weixin.js

@@ -0,0 +1,32 @@
+import express from 'express'
+import { EventEmitter } from 'node:events'
+
+export class WeixinAdapter extends EventEmitter {
+    constructor(opts = {}) {
+        super()
+        this.platform = 'weixin'
+        this.token = opts.token || process.env.WEIXIN_TOKEN
+        this.port = opts.port || 0
+        this.api = opts.api || "https://api.weixin.qq.com/cgi-bin/message/send"
+        this._server = null
+    }
+    getRequiredEnv() { return ["WEIXIN_TOKEN"] }
+    async start() {
+        if (!this.token) throw new Error('WeixinAdapter: ' + this.getRequiredEnv().join(', ') + ' required')
+        const app = express()
+        app.use(express.json())
+        app.post('/webhook', (req, res) => {
+            const text = req.body?.text || req.body?.message?.text || req.body?.content || ''
+            const from = req.body?.from || req.body?.user_id || req.body?.sender_id || ''
+            this.emit('message', { from: String(from), text, raw: req.body })
+            res.json({ ok: true })
+        })
+        await new Promise(r => { this._server = app.listen(this.port, () => r()) })
+        this.port = this._server.address().port
+    }
+    async stop() { if (this._server) await new Promise(r => this._server.close(() => r())) }
+    async send(reply) {
+        if (!this.token) throw new Error('WeixinAdapter: token required')
+        return fetch(this.api, { method: 'POST', headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' }, body: JSON.stringify({ to: reply.to, text: reply.text }) }).then(r => r.json())
+    }
+}

package/src/gateway/platforms/whatsapp.js

@@ -0,0 +1,40 @@
+import express from 'express'
+import { EventEmitter } from 'node:events'
+
+export class WhatsappAdapter extends EventEmitter {
+    constructor(opts = {}) {
+        super()
+        this.platform = 'whatsapp'
+        this.token = opts.token || process.env.WHATSAPP_API_TOKEN
+        this.phoneId = opts.phoneId || process.env.WHATSAPP_PHONE_NUMBER_ID
+        this.verifyToken = opts.verifyToken || process.env.WHATSAPP_VERIFY_TOKEN || 'freddie'
+        this.port = opts.port || 0
+        this.api = opts.api || 'https://graph.facebook.com/v20.0'
+        this._server = null
+    }
+    getRequiredEnv() { return ['WHATSAPP_API_TOKEN', 'WHATSAPP_PHONE_NUMBER_ID'] }
+    async start() {
+        if (!this.token || !this.phoneId) throw new Error('WhatsappAdapter: WHATSAPP_API_TOKEN + WHATSAPP_PHONE_NUMBER_ID required')
+        const app = express()
+        app.use(express.json())
+        app.get('/webhook', (req, res) => {
+            if (req.query['hub.verify_token'] === this.verifyToken) return res.send(req.query['hub.challenge'])
+            res.sendStatus(403)
+        })
+        app.post('/webhook', (req, res) => {
+            const entries = req.body?.entry || []
+            for (const e of entries) for (const c of (e.changes || [])) {
+                const msgs = c.value?.messages || []
+                for (const m of msgs) this.emit('message', { from: m.from, text: m.text?.body || '', raw: m })
+            }
+            res.json({ ok: true })
+        })
+        await new Promise(r => { this._server = app.listen(this.port, () => r()) })
+        this.port = this._server.address().port
+    }
+    async stop() { if (this._server) await new Promise(r => this._server.close(() => r())) }
+    async send(reply) {
+        if (!this.token) throw new Error('WhatsappAdapter: token required')
+        return fetch(`${this.api}/${this.phoneId}/messages`, { method: 'POST', headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' }, body: JSON.stringify({ messaging_product: 'whatsapp', to: reply.to, text: { body: reply.text } }) }).then(r => r.json())
+    }
+}

package/src/gateway/platforms/yuanbao.js

@@ -0,0 +1,9 @@
+import { BasePlatformAdapter } from '../base.js'
+export class YuanbaoAdapter extends BasePlatformAdapter {
+    constructor(opts = {}) { super({ ...opts, platform: 'yuanbao' }); this.token = opts.token || process.env.YUANBAO_API_KEY; this.api = opts.api || 'https://api.hunyuan.cloud.tencent.com/v1' }
+    getRequiredEnv() { return ['YUANBAO_API_KEY'] }
+    async send(reply) {
+        const r = await fetch(this.api + '/chat/completions', { method: 'POST', headers: { authorization: 'Bearer ' + this.token, 'content-type': 'application/json' }, body: JSON.stringify({ model: 'hunyuan-pro', messages: [{ role: 'user', content: reply.text }] }) })
+        return await r.json()
+    }
+}

package/src/gateway/platforms/yuanbao_media.js

@@ -0,0 +1,5 @@
+export async function uploadMedia({ token, file, mime = 'image/png' }) {
+    if (!token) throw new Error('yuanbao token required')
+    const r = await fetch('https://api.hunyuan.cloud.tencent.com/v1/files', { method: 'POST', headers: { authorization: 'Bearer ' + token, 'content-type': mime }, body: file })
+    return await r.json()
+}

package/src/gateway/platforms/yuanbao_proto.js

@@ -0,0 +1,9 @@
+export function buildChatPayload({ model = 'hunyuan-pro', messages, stream = false, tools = [] }) {
+    return { model, messages, stream, ...(tools.length ? { tools: tools.map(t => ({ type: 'function', function: t })) } : {}) }
+}
+export function parseChatResponse(json) {
+    const choice = json?.choices?.[0]
+    if (!choice) return { content: '', tool_calls: [] }
+    const tc = (choice.message?.tool_calls || []).map(c => ({ id: c.id, name: c.function?.name, arguments: c.function?.arguments ? JSON.parse(c.function.arguments) : {} }))
+    return { content: choice.message?.content || '', tool_calls: tc }
+}

package/src/gateway/platforms/yuanbao_sticker.js

@@ -0,0 +1,6 @@
+export const STICKER_PACK = ['cute', 'work', 'celebration', 'thinking', 'thumbs-up']
+export function buildStickerMessage({ to, sticker }) {
+    if (!STICKER_PACK.includes(sticker)) throw new Error('unknown sticker: ' + sticker)
+    return { to, type: 'sticker', sticker }
+}
+export function listStickers() { return STICKER_PACK }

package/src/gateway/run.js

@@ -0,0 +1,42 @@
+import { logger } from '../observability/log.js'
+import { runTurn } from '../agent/machine.js'
+
+const log = logger('gateway')
+
+export class Gateway {
+    constructor({ platforms = {}, callLLM = null } = {}) {
+        this.platforms = new Map()
+        this.callLLM = callLLM
+        this.hooks = { inbound: [], outbound: [] }
+        for (const [name, adapter] of Object.entries(platforms)) this.register(name, adapter)
+    }
+    register(name, adapter) {
+        this.platforms.set(name, adapter)
+        adapter.on?.('message', (m) => this.handleInbound(name, m))
+    }
+    addHook(stage, fn) { this.hooks[stage].push(fn) }
+    async start() {
+        for (const a of this.platforms.values()) await a.start?.()
+        log.info('gateway started', { platforms: [...this.platforms.keys()] })
+    }
+    async stop() {
+        for (const a of this.platforms.values()) await a.stop?.()
+        log.info('gateway stopped')
+    }
+    async handleInbound(platform, msg) {
+        log.info('inbound', { platform, from: msg.from, len: (msg.text || '').length })
+        let cur = { ...msg, platform }
+        for (const h of this.hooks.inbound) cur = (await h(cur)) || cur
+        const result = await runTurn({ prompt: cur.text || '', callLLM: this.callLLM })
+        let reply = { to: msg.from, text: result.result || result.error || '', platform, result }
+        for (const h of this.hooks.outbound) reply = (await h(reply)) || reply
+        const adapter = this.platforms.get(platform)
+        await adapter.send?.(reply)
+        return reply
+    }
+}
+
+export const bootMdHook = async (m) => {
+    if ((m.text || '').startsWith('/boot')) m.text = (m.text || '').replace(/^\/boot\s*/, '').trim() || 'hello'
+    return m
+}

package/src/gateway/service.js

@@ -0,0 +1,143 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawn, spawnSync } from 'node:child_process'
+
+const PLAT = process.platform
+
+function profileSuffix() { return process.env.FREDDIE_PROFILE ? '-' + process.env.FREDDIE_PROFILE : '' }
+
+export function serviceName() { return 'freddie-gateway' + profileSuffix() }
+
+export function isLinux() { return PLAT === 'linux' }
+export function isMacos() { return PLAT === 'darwin' }
+export function isWindows() { return PLAT === 'win32' }
+
+export function supportsSystemdServices() {
+    if (!isLinux()) return false
+    if (!fs.existsSync('/run/systemd/system')) return false
+    return true
+}
+
+function userSystemdUnitDir() {
+    return path.join(os.homedir(), '.config', 'systemd', 'user')
+}
+
+export function getSystemdUnitPath() {
+    return path.join(userSystemdUnitDir(), serviceName() + '.service')
+}
+
+export function renderSystemdUnit({ execStart, workingDir = process.cwd(), envVars = {} } = {}) {
+    const env = Object.entries(envVars).map(([k, v]) => `Environment=${k}=${v}`).join('\n')
+    return `[Unit]
+Description=Freddie Gateway${profileSuffix()}
+After=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${workingDir}
+ExecStart=${execStart}
+Restart=on-failure
+RestartSec=5
+${env}
+
+[Install]
+WantedBy=default.target
+`
+}
+
+export function installSystemdUnit({ execStart, workingDir, envVars } = {}) {
+    if (!supportsSystemdServices()) throw new Error('systemd user services not available')
+    fs.mkdirSync(userSystemdUnitDir(), { recursive: true })
+    fs.writeFileSync(getSystemdUnitPath(), renderSystemdUnit({ execStart, workingDir, envVars }))
+    spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' })
+    return getSystemdUnitPath()
+}
+
+export function controlSystemd(verb) {
+    if (!supportsSystemdServices()) throw new Error('systemd user services not available')
+    const r = spawnSync('systemctl', ['--user', verb, serviceName()], { encoding: 'utf8' })
+    return { ok: r.status === 0, stdout: r.stdout || '', stderr: r.stderr || '', code: r.status }
+}
+
+export function getLaunchdPlistPath() {
+    return path.join(os.homedir(), 'Library', 'LaunchAgents', 'co.freddie.gateway' + profileSuffix() + '.plist')
+}
+
+export function renderLaunchdPlist({ execStart, workingDir = process.cwd(), envVars = {} } = {}) {
+    const args = execStart.split(/\s+/)
+    const argXml = args.map(a => `<string>${a.replace(/&/g, '&amp;').replace(/</g, '&lt;')}</string>`).join('\n            ')
+    const envXml = Object.entries(envVars).map(([k, v]) => `<key>${k}</key><string>${v}</string>`).join('\n            ')
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key><string>co.freddie.gateway${profileSuffix()}</string>
+    <key>WorkingDirectory</key><string>${workingDir}</string>
+    <key>ProgramArguments</key>
+    <array>
+            ${argXml}
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+            ${envXml}
+    </dict>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+</dict>
+</plist>
+`
+}
+
+export function installLaunchdPlist({ execStart, workingDir, envVars } = {}) {
+    if (!isMacos()) throw new Error('launchd is macOS-only')
+    fs.mkdirSync(path.dirname(getLaunchdPlistPath()), { recursive: true })
+    fs.writeFileSync(getLaunchdPlistPath(), renderLaunchdPlist({ execStart, workingDir, envVars }))
+    return getLaunchdPlistPath()
+}
+
+export function controlLaunchd(verb) {
+    if (!isMacos()) throw new Error('launchd is macOS-only')
+    const map = { start: 'load', stop: 'unload', restart: 'kickstart' }
+    const arg = map[verb] || verb
+    const r = spawnSync('launchctl', [arg, getLaunchdPlistPath()], { encoding: 'utf8' })
+    return { ok: r.status === 0, stdout: r.stdout || '', stderr: r.stderr || '', code: r.status }
+}
+
+export function findGatewayPids() {
+    if (isWindows()) {
+        const r = spawnSync('wmic', ['process', 'get', 'ProcessId,CommandLine', '/format:csv'], { encoding: 'utf8' })
+        if (r.status !== 0) return []
+        const lines = (r.stdout || '').split(/\r?\n/).filter(l => /freddie.*gateway/i.test(l))
+        return lines.map(l => parseInt(l.split(',').pop(), 10)).filter(n => Number.isFinite(n))
+    }
+    const r = spawnSync('pgrep', ['-f', 'freddie.*gateway'], { encoding: 'utf8' })
+    if (r.status !== 0) return []
+    return (r.stdout || '').trim().split('\n').filter(Boolean).map(n => parseInt(n, 10))
+}
+
+export function killGatewayProcesses({ signal = 'SIGTERM' } = {}) {
+    const pids = findGatewayPids()
+    let killed = 0
+    for (const pid of pids) {
+        try { process.kill(pid, signal); killed++ } catch {}
+    }
+    return { pids, killed }
+}
+
+export function getRuntimeSnapshot() {
+    return {
+        platform: PLAT,
+        serviceName: serviceName(),
+        systemd: { available: supportsSystemdServices(), unitPath: getSystemdUnitPath() },
+        launchd: { available: isMacos(), plistPath: getLaunchdPlistPath() },
+        pids: findGatewayPids(),
+    }
+}
+
+export function startDetached({ execStart, workingDir = process.cwd(), envVars = {} } = {}) {
+    const args = execStart.split(/\s+/)
+    const child = spawn(args[0], args.slice(1), { cwd: workingDir, env: { ...process.env, ...envVars }, detached: true, stdio: 'ignore' })
+    child.unref()
+    return child.pid
+}

package/src/home.js

@@ -0,0 +1,44 @@
+import os from 'node:os'
+import path from 'node:path'
+import fs from 'node:fs'
+
+let _cached = null
+
+export function getFophHome() {
+    if (_cached) return _cached
+    const env = process.env.FREDDIE_HOME
+    if (env) { _cached = env; ensure(env); return env }
+    const profile = process.env.FREDDIE_PROFILE
+    const root = path.join(os.homedir(), '.freddie')
+    const home = profile ? path.join(root, 'profiles', profile) : root
+    _cached = home
+    ensure(home)
+    return home
+}
+
+export function displayFophHome() {
+    const profile = process.env.FREDDIE_PROFILE
+    return profile ? `~/.freddie/profiles/${profile}` : '~/.freddie'
+}
+
+export function applyProfileOverride(name) {
+    if (!name || name === 'default') { delete process.env.FREDDIE_PROFILE; _cached = null; return }
+    process.env.FREDDIE_PROFILE = name
+    _cached = null
+}
+
+export function getProfilesRoot() {
+    if (process.env.FREDDIE_PROFILES_ROOT) return process.env.FREDDIE_PROFILES_ROOT
+    if (process.env.FREDDIE_HOME) return path.join(process.env.FREDDIE_HOME, 'profiles')
+    return path.join(os.homedir(), '.freddie', 'profiles')
+}
+
+export function listProfiles() {
+    const root = getProfilesRoot()
+    if (!fs.existsSync(root)) return []
+    return fs.readdirSync(root).filter(n => fs.statSync(path.join(root, n)).isDirectory())
+}
+
+export function resetCacheForTests() { _cached = null }
+
+function ensure(p) { try { fs.mkdirSync(p, { recursive: true }) } catch {} }