@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/dist/src/web-search.js

@@ -0,0 +1,302 @@
+import { readFileSync, statSync } from 'node:fs';
+import { guardedRequest } from './web-guard.js';
+import { decodeEntities, stripTags } from './web-fetch.js';
+export const SEARCH_KINDS = ['general', 'code', 'package', 'paper', 'wiki'];
+const KEYLESS = ['wikipedia', 'stackexchange', 'github', 'npm', 'pypi', 'arxiv', 'hackernews'];
+const ROUTES = {
+    code: ['github', 'stackexchange'],
+    package: ['npm', 'pypi'],
+    paper: ['arxiv'],
+    wiki: ['wikipedia'],
+};
+const GENERAL_KEYLESS = ['wikipedia', 'stackexchange', 'hackernews'];
+const CACHE_TTL_MS = 10 * 60_000;
+const CACHE_MAX = 200;
+const clean = (s, max = 400) => decodeEntities(stripTags(String(s ?? '')))
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+const q = encodeURIComponent;
+export class WebSearch {
+    transport;
+    providers;
+    now;
+    backends = new Map();
+    last = new Map();
+    cache = new Map();
+    constructor(opts = {}) {
+        this.transport =
+            opts.transport ??
+                ((url, o = {}) => guardedRequest(url, { ...o, maxBytes: 1_000_000, timeoutMs: 12_000 }));
+        this.providers = opts.providers ?? [];
+        this.now = opts.now ?? Date.now;
+        const json = async (url, o) => {
+            const r = await this.transport(url, {
+                ...o,
+                headers: { accept: 'application/json', ...o?.headers },
+            });
+            if (r.status < 200 || r.status >= 300)
+                throw new Error(`HTTP ${r.status}`);
+            return JSON.parse(r.body);
+        };
+        const add = (name, run, intervalMs = 1000) => this.backends.set(name, { name, run, intervalMs });
+        add('wikipedia', async (s, n) => ((await json(`https://en.wikipedia.org/w/api.php?action=query&list=search&format=json&utf8=1&srlimit=${n}&srsearch=${q(s)}`)).query?.search ?? []).map((h) => ({
+            title: clean(h.title, 200),
+            url: 'https://en.wikipedia.org/wiki/' + encodeURIComponent(String(h.title).replace(/ /g, '_')),
+            snippet: clean(h.snippet),
+            source: 'wikipedia',
+        })));
+        add('stackexchange', async (s, n) => ((await json(`https://api.stackexchange.com/2.3/search/advanced?order=desc&sort=relevance&site=stackoverflow&pagesize=${n}&q=${q(s)}`)).items ?? []).map((h) => ({
+            title: clean(h.title, 200),
+            url: String(h.link),
+            snippet: `score ${h.score ?? 0}${h.is_answered ? ', answered' : ''}`,
+            source: 'stackexchange',
+        })));
+        add('github', async (s, n) => ((await json(`https://api.github.com/search/repositories?per_page=${n}&q=${q(s)}`, {
+            headers: {
+                accept: 'application/vnd.github+json',
+                ...(opts.githubToken ? { authorization: 'Bearer ' + opts.githubToken } : {}),
+            },
+        })).items ?? []).map((h) => ({
+            title: clean(h.full_name, 200),
+            url: String(h.html_url),
+            snippet: `${clean(h.description)} (${h.stargazers_count ?? 0} stars)`.trim(),
+            source: 'github',
+        })), 
+        // Unauthenticated repository search allows 10 requests a minute.
+        opts.githubToken ? 2000 : 6000);
+        add('npm', async (s, n) => ((await json(`https://registry.npmjs.org/-/v1/search?size=${n}&text=${q(s)}`)).objects ?? []).map((o) => ({
+            title: `${clean(o.package?.name, 200)}@${clean(o.package?.version, 40)}`,
+            url: String(o.package?.links?.npm ?? `https://www.npmjs.com/package/${o.package?.name}`),
+            snippet: clean(o.package?.description),
+            source: 'npm',
+        })));
+        // PyPI has no search API; its official JSON API answers an exact project name.
+        add('pypi', async (s) => {
+            const name = s.trim();
+            if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(name))
+                return [];
+            const r = await this.transport(`https://pypi.org/pypi/${q(name)}/json`, {
+                headers: { accept: 'application/json' },
+            });
+            if (r.status === 404)
+                return [];
+            if (r.status < 200 || r.status >= 300)
+                throw new Error(`HTTP ${r.status}`);
+            const info = JSON.parse(r.body).info ?? {};
+            return [
+                {
+                    title: `${clean(info.name, 200)} ${clean(info.version, 40)}`.trim(),
+                    url: String(info.package_url ?? `https://pypi.org/project/${name}/`),
+                    snippet: clean(info.summary),
+                    source: 'pypi',
+                },
+            ];
+        });
+        add('arxiv', async (s, n) => {
+            const r = await this.transport(`https://export.arxiv.org/api/query?max_results=${n}&search_query=all:${q(s)}`, { headers: { accept: 'application/atom+xml' } });
+            if (r.status < 200 || r.status >= 300)
+                throw new Error(`HTTP ${r.status}`);
+            return [...r.body.matchAll(/<entry>([\s\S]*?)<\/entry>/g)].map((m) => {
+                const tag = (t) => new RegExp(`<${t}[^>]*>([\\s\\S]*?)</${t}>`).exec(m[1])?.[1] ?? '';
+                return {
+                    title: clean(tag('title'), 300),
+                    url: clean(tag('id'), 300),
+                    snippet: clean(tag('summary')),
+                    source: 'arxiv',
+                };
+            });
+        }, 3000);
+        add('hackernews', async (s, n) => ((await json(`https://hn.algolia.com/api/v1/search?hitsPerPage=${n}&query=${q(s)}`)).hits ??
+            []).map((h) => ({
+            title: clean(h.title ?? h.story_title, 200),
+            url: String(h.url ?? `https://news.ycombinator.com/item?id=${h.objectID}`),
+            snippet: `${h.points ?? 0} points on Hacker News`,
+            source: 'hackernews',
+        })));
+        this.providers.forEach((p, i) => {
+            const name = this.providers.findIndex((o) => o.type === p.type) === i ? p.type : `${p.type}-${i}`;
+            if (p.type === 'searxng')
+                add(name, async (s, n) => ((await json(`${p.url.replace(/\/+$/, '')}/search?format=json&q=${q(s)}`)).results ?? [])
+                    .slice(0, n)
+                    .map((h) => ({
+                    title: clean(h.title, 200),
+                    url: String(h.url),
+                    snippet: clean(h.content),
+                    source: p.type,
+                })));
+            else if (p.type === 'brave')
+                add(name, async (s, n) => ((await json(`https://api.search.brave.com/res/v1/web/search?count=${n}&q=${q(s)}`, {
+                    headers: { 'x-subscription-token': p.key },
+                })).web?.results ?? []).map((h) => ({
+                    title: clean(h.title, 200),
+                    url: String(h.url),
+                    snippet: clean(h.description),
+                    source: p.type,
+                })));
+            else if (p.type === 'tavily')
+                add(name, async (s, n) => ((await json('https://api.tavily.com/search', {
+                    method: 'POST',
+                    headers: { authorization: 'Bearer ' + p.key },
+                    body: JSON.stringify({ query: s, max_results: n }),
+                })).results ?? []).map((h) => ({
+                    title: clean(h.title, 200),
+                    url: String(h.url),
+                    snippet: clean(h.content),
+                    source: p.type,
+                })));
+            else
+                add(name, async (s, n) => ((await json('https://api.exa.ai/search', {
+                    method: 'POST',
+                    headers: { 'x-api-key': p.key },
+                    body: JSON.stringify({ query: s, numResults: n }),
+                })).results ?? []).map((h) => ({
+                    title: clean(h.title, 200),
+                    url: String(h.url),
+                    snippet: clean(h.text ?? h.summary),
+                    source: p.type,
+                })));
+        });
+    }
+    /** What is enabled, for health and manifests: provider types only, never keys or URLs' secrets. */
+    describe() {
+        return { providers: this.providers.map((p) => p.type), keyless: [...KEYLESS] };
+    }
+    order(kind) {
+        if (kind !== 'general')
+            return ROUTES[kind];
+        const providerNames = [...this.backends.keys()].filter((n) => !KEYLESS.includes(n));
+        return [...providerNames, ...GENERAL_KEYLESS];
+    }
+    async search(input) {
+        const query = String(input.query ?? '')
+            .trim()
+            .slice(0, 300);
+        if (!query)
+            throw new Error('An empty query cannot be searched');
+        const kind = input.kind ?? 'general';
+        if (!SEARCH_KINDS.includes(kind))
+            throw new Error('Unknown search kind');
+        const limit = Math.max(1, Math.min(10, Math.floor(input.limit ?? 5)));
+        const key = `${kind}\u0000${query.toLowerCase()}\u0000${limit}`;
+        const hit = this.cache.get(key);
+        if (hit && this.now() - hit.at < CACHE_TTL_MS)
+            return { ...hit.value, cached: true };
+        const results = [];
+        const seen = new Set();
+        const tried = [];
+        for (const name of this.order(kind)) {
+            if (results.length >= limit)
+                break;
+            const b = this.backends.get(name);
+            const last = this.last.get(name);
+            if (last !== undefined && this.now() - last < b.intervalMs) {
+                tried.push({ backend: name, ok: false, ms: 0, error: 'rate-limited' });
+                continue;
+            }
+            this.last.set(name, this.now());
+            const started = Date.now();
+            try {
+                const got = await b.run(query, limit - results.length);
+                let count = 0;
+                for (const r of got) {
+                    if (!/^https?:\/\//.test(r.url) || seen.has(r.url))
+                        continue;
+                    seen.add(r.url);
+                    results.push(r);
+                    count++;
+                    if (results.length >= limit)
+                        break;
+                }
+                tried.push({ backend: name, ok: true, count, ms: Date.now() - started });
+            }
+            catch (error) {
+                tried.push({
+                    backend: name,
+                    ok: false,
+                    ms: Date.now() - started,
+                    error: String(error.message ?? error).slice(0, 200),
+                });
+            }
+        }
+        const value = { query, kind, results, tried };
+        // Cache only a complete answer: one assembled around a skipped or failing backend would
+        // keep that gap for the cache's lifetime.
+        if (results.length && tried.every((t) => t.ok)) {
+            if (this.cache.size >= CACHE_MAX)
+                this.cache.delete(this.cache.keys().next().value);
+            this.cache.set(key, { at: this.now(), value });
+        }
+        return value;
+    }
+}
+/** Reads the operator's web search config: providers in order, keys from env or a private file. */
+export function loadWebSearchConfig(path, env = process.env) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error(`Web search config ${path} is not readable JSON`);
+    }
+    const top = raw;
+    if (!top || typeof top !== 'object' || Array.isArray(top))
+        throw new Error('Web search config must be an object');
+    for (const k of Object.keys(top))
+        if (!['providers', 'github_token_env'].includes(k))
+            throw new Error(`Web search config: unknown field ${k}`);
+    const secret = (p, label) => {
+        const hasEnv = typeof p.key_env === 'string' && p.key_env;
+        const hasFile = typeof p.key_file === 'string' && p.key_file;
+        if ('key' in p || (!hasEnv && !hasFile) || (hasEnv && hasFile))
+            throw new Error(`${label} needs exactly one of key_env or key_file (never the key itself)`);
+        if (hasEnv) {
+            const v = env[p.key_env];
+            if (!v)
+                throw new Error(`${label}: ${p.key_env} is not set`);
+            return v.trim();
+        }
+        const file = p.key_file;
+        const st = statSync(file);
+        if (st.mode & 0o077)
+            throw new Error(`${label}: ${file} is readable by others; chmod 600 it`);
+        return readFileSync(file, 'utf8').trim();
+    };
+    const providers = [];
+    const list = top.providers ?? [];
+    if (!Array.isArray(list) || list.length > 8)
+        throw new Error('providers must be a list of up to 8');
+    list.forEach((entry, i) => {
+        const p = entry;
+        const label = `providers[${i}]`;
+        const type = p?.type;
+        if (type === 'searxng') {
+            for (const k of Object.keys(p))
+                if (!['type', 'url'].includes(k))
+                    throw new Error(`${label}: unknown field ${k}`);
+            let u;
+            try {
+                u = new URL(String(p.url));
+            }
+            catch {
+                throw new Error(`${label}: url must be http or https`);
+            }
+            if (u.protocol !== 'https:' && u.protocol !== 'http:')
+                throw new Error(`${label}: url must be http or https`);
+            providers.push({ type, url: u.toString() });
+        }
+        else if (type === 'brave' || type === 'tavily' || type === 'exa') {
+            for (const k of Object.keys(p))
+                if (!['type', 'key_env', 'key_file', 'key'].includes(k))
+                    throw new Error(`${label}: unknown field ${k}`);
+            providers.push({ type, key: secret(p, label) });
+        }
+        else
+            throw new Error(`${label}: unknown provider (searxng, brave, tavily or exa)`);
+    });
+    const ghEnv = top.github_token_env;
+    if (ghEnv !== undefined && typeof ghEnv !== 'string')
+        throw new Error('github_token_env must be a name');
+    const githubToken = ghEnv ? env[ghEnv] : undefined;
+    return { providers, ...(githubToken ? { githubToken } : {}) };
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@superjackfruitlabs/salaam",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@superjackfruitlabs/salaam",
-      "version": "0.0.3",
+      "version": "0.0.5",
       "bundleDependencies": [
         "@earendil-works/pi-ai",
         "@earendil-works/pi-coding-agent",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superjackfruitlabs/salaam",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/src/acp-desk.ts

@@ -0,0 +1,155 @@
+import { isAbsolute, join } from 'node:path';
+import type { PermissionMode, PermissionPolicy, SessionAccess } from './autonomy.js';
+import type { LocalEdit } from './local-edits.js';
+import type { TurnCheckpoint } from './turn-rewind.js';
+import { relativeTime } from './session-pick.js';
+
+/** What an editor shows for a desk session: the same choices as Shift+Tab, plus full access.
+ * YOLO is listed only while it is on, because turning it on needs "yolo" typed in the terminal. */
+export type DeskMode = 'review' | 'accept-edits' | 'auto' | 'full-access' | 'yolo';
+const MODES: { id: DeskMode; name: string; description: string }[] = [
+  { id: 'review', name: 'Review', description: 'Asks before every edit and command' },
+  {
+    id: 'accept-edits',
+    name: 'Accept edits',
+    description: 'Edits in the project apply at once; commands ask',
+  },
+  {
+    id: 'auto',
+    name: 'Auto',
+    description: 'Project edits and sandboxed commands run at once; the rest asks',
+  },
+  {
+    id: 'full-access',
+    name: 'Full access',
+    description: 'No OS sandbox; only dangerous commands ask',
+  },
+];
+const YOLO = {
+  id: 'yolo' as const,
+  name: 'YOLO',
+  description: 'No approvals at all and no sandbox. Turn it off in the terminal with /yolo',
+};
+
+export interface DeskPermissions {
+  policy: PermissionPolicy;
+  full_access_allowed?: boolean;
+}
+export function deskMode(policy: PermissionPolicy): DeskMode | PermissionMode {
+  if (policy.access === 'yolo') return 'yolo';
+  if (policy.access === 'full') return 'full-access';
+  return policy.mode;
+}
+/** `modes` and the matching `configOptions`, kept in step (ACP asks agents to send both). */
+export function modeState(p: DeskPermissions) {
+  const current = deskMode(p.policy);
+  const list = MODES.filter((m) => m.id !== 'full-access' || p.full_access_allowed !== false);
+  if (current === 'yolo') list.push(YOLO);
+  else if (!list.some((m) => m.id === current))
+    list.unshift({ id: current as DeskMode, name: current, description: 'Set in the terminal' });
+  return {
+    modes: { currentModeId: current, availableModes: list },
+    configOptions: [
+      {
+        id: 'mode',
+        name: 'Mode',
+        category: 'mode',
+        type: 'select',
+        currentValue: current,
+        options: list.map((m) => ({ value: m.id, name: m.name, description: m.description })),
+      },
+    ],
+  };
+}
+/** The policy a chosen mode asks for. Picking a mode turns full access off; full access runs in
+ * auto, so edits and commands go ahead and only dangerous commands ask. */
+export function policyFor(
+  mode: string,
+  allowed: { full?: boolean } = {},
+): { mode: PermissionMode; paths: string[]; access?: SessionAccess } {
+  if (mode === 'review' || mode === 'accept-edits' || mode === 'auto') return { mode, paths: [] };
+  if (mode === 'full-access') {
+    if (allowed.full === false)
+      throw new Error(
+        'The operator does not allow full access on this host. Commands stay in the OS sandbox.',
+      );
+    return { mode: 'auto', paths: [], access: 'full' };
+  }
+  if (mode === 'yolo')
+    throw new Error('YOLO is turned on only in the terminal: run /yolo there and type yolo.');
+  throw new Error('Unknown mode ' + JSON.stringify(mode));
+}
+export const FULL_ACCESS_WARNING =
+  'Later commands in this session run WITHOUT the OS sandbox: they can read and change any file your user can, and reach the network directly. They run without asking, except commands the danger check calls dangerous (force pushes, deletes, publishing, credentials, anything it cannot read), which still ask and say why. Pick another mode to turn it off.';
+
+/** ACP diff content for an edit request: absolute paths, null old text for a new file. */
+export function editDiffs(root: string, edits: readonly LocalEdit[]) {
+  return edits.map((e) => ({
+    type: 'diff' as const,
+    path: isAbsolute(e.path) ? e.path : join(root, e.path),
+    oldText: e.before,
+    newText: e.after,
+  }));
+}
+
+/** Why an approval asks, from the reviewed text and the mode, in one line. */
+export function askReason(value: string, mode: PermissionMode | undefined): string {
+  const danger = /^Dangerous \(([^)]+)\): (.*)$/m.exec(value);
+  if (danger) return `Asks because this command is dangerous (${danger[1]}): ${danger[2]}`;
+  const outside = /^Outside the sandbox: (.*?)\. This one command/m.exec(value);
+  if (outside) return `Asks because it wants to run outside the sandbox: ${outside[1]}`;
+  if (/^Publishes: /m.test(value))
+    return 'Asks because pushing and opening pull requests always ask.';
+  if (/^May listen: /m.test(value))
+    return 'Asks because this command may accept network connections; macOS cannot limit it to localhost.';
+  const edit = /^(---|\+\+\+) /m.test(value) && !/\nCommand:\n/.test(value);
+  if (mode === 'review') return 'Asks because review mode asks before every edit and command.';
+  if (mode === 'accept-edits' && !edit)
+    return 'Asks because accept edits still asks before commands.';
+  if (mode === 'auto')
+    return edit
+      ? 'Asks because this edit is outside what auto mode approves on its own.'
+      : 'Asks because auto mode approves only sandboxed commands it can read.';
+  return 'Asks because nothing approves this request on its own.';
+}
+
+export const DESK_COMMANDS = [
+  {
+    name: 'rewind',
+    description: 'Put the files back as they were before an earlier turn',
+    input: { hint: 'turn number (leave empty to list turns)' },
+  },
+];
+/** `/rewind`, `/rewind 3`. Anything else is not a desk command and goes to the model. */
+export function parseDeskCommand(text: string): { command: 'rewind'; turn?: number } | null {
+  const match = /^\/rewind(?:\s+(\S+))?\s*$/.exec(text.trim());
+  if (!match) return null;
+  if (match[1] === undefined) return { command: 'rewind' };
+  const turn = Number(match[1]);
+  if (!Number.isSafeInteger(turn) || turn < 1)
+    throw new Error('Use /rewind with a turn number from the list, e.g. /rewind 3.');
+  return { command: 'rewind', turn };
+}
+export function checkpointList(points: readonly TurnCheckpoint[], now = Date.now()): string {
+  if (!points.length) return 'No turns to go back to yet.';
+  return [
+    'Turns you can go back to (the files as they were before each turn ran):',
+    '',
+    ...points
+      .slice()
+      .reverse()
+      .map(
+        (p) =>
+          `- Turn ${p.turn} · ${relativeTime(p.at, now)} · ${p.text.split('\n')[0]!.slice(0, 80)}`,
+      ),
+    '',
+    'Run /rewind followed by a turn number to review and restore its files.',
+  ].join('\n');
+}
+/** Zed cannot follow a rewind into a new session, so from the editor only files are restored. */
+export const REWIND_CHOICES = [
+  { optionId: 'files', name: 'Restore files', kind: 'allow_once' },
+  { optionId: 'cancel', name: 'Cancel', kind: 'reject_once' },
+];
+export const CONVERSATION_REWIND_NOTE =
+  'To go back in the conversation too, run /rewind in the terminal (salaam -c opens this session): it continues in a new session.';