agent-sh 0.14.9 → 0.14.10

package/dist/agent/index.js

@@ -14,6 +14,9 @@ import activateOpenrouter from "./providers/openrouter.js";
 import activateOpenai from "./providers/openai.js";
 import activateOpenaiCompatible from "./providers/openai-compatible.js";
 import activateDeepseek from "./providers/deepseek.js";
+import activateOllama from "./providers/ollama.js";
+import activateZaiCodingPlan from "./providers/zai-coding-plan.js";
+import activateOpencode from "./providers/opencode.js";
 import { findBash } from "../utils/executor.js";
 import { createBashTool } from "./tools/bash.js";
 import { createPwshTool } from "./tools/pwsh.js";
@@ -501,4 +504,7 @@ export function activateAgent(ctx) {
     if (process.env.OPENAI_BASE_URL)
         activateOpenaiCompatible(agentCtx);
     activateDeepseek(agentCtx);
+    activateOllama(agentCtx);
+    activateZaiCodingPlan(agentCtx);
+    activateOpencode(agentCtx);
 }

package/dist/agent/providers/ollama.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ollama provider — local daemon or Ollama Cloud.
+ *
+ * Cloud auth:  agent-sh auth login ollama-cloud
+ * Local host:  OLLAMA_HOST (default http://localhost:11434)
+ *
+ * Catalog comes from /api/tags; per-model context length is fetched
+ * from /api/show. Chat goes through the OpenAI-compatible /v1 shim.
+ */
+import type { AgentContext } from "../host-types.js";
+export default function activate(ctx: AgentContext): void;

package/dist/agent/providers/ollama.js

@@ -0,0 +1,72 @@
+import { resolveApiKey } from "../../cli/auth/keys.js";
+const ECHO_REASONING_PATTERNS = [/deepseek/i];
+export default function activate(ctx) {
+    const cloudKey = resolveApiKey("ollama-cloud").key ?? process.env.OLLAMA_API_KEY;
+    const host = cloudKey
+        ? "https://ollama.com"
+        : (process.env.OLLAMA_HOST ?? "http://localhost:11434").replace(/\/$/, "");
+    const id = cloudKey ? "ollama-cloud" : "ollama";
+    const sdkKey = cloudKey || "no-key";
+    const noAuth = !cloudKey;
+    const baseURL = `${host}/v1`;
+    const headers = {};
+    if (cloudKey)
+        headers.Authorization = `Bearer ${cloudKey}`;
+    ctx.agent.providers.configure(id, {
+        reasoningParams: (level) => {
+            if (level === "off")
+                return { reasoning_effort: "none" };
+            return { reasoning_effort: level === "xhigh" ? "high" : level };
+        },
+    });
+    ctx.agent.providers.register({ id, apiKey: sdkKey, baseURL, models: [], noAuth });
+    fetchCatalog(host, headers).then((models) => {
+        if (models.length === 0)
+            return;
+        ctx.agent.providers.register({
+            id,
+            apiKey: sdkKey,
+            baseURL,
+            defaultModel: models[0].id,
+            models,
+            noAuth,
+        });
+    }).catch(() => { });
+}
+async function fetchCatalog(host, headers) {
+    const tagsRes = await fetch(`${host}/api/tags`, { headers });
+    if (!tagsRes.ok)
+        return [];
+    const tagsData = await tagsRes.json();
+    const names = (tagsData.models ?? []).map((m) => m.name);
+    if (names.length === 0)
+        return [];
+    const ctxs = await Promise.all(names.map((name) => fetchContextLength(host, headers, name).catch(() => undefined)));
+    return names.map((name, i) => ({
+        id: name,
+        contextWindow: ctxs[i],
+        echoReasoning: ECHO_REASONING_PATTERNS.some((re) => re.test(name)),
+    }));
+}
+async function fetchContextLength(host, headers, name) {
+    const res = await fetch(`${host}/api/show`, {
+        method: "POST",
+        headers: { ...headers, "Content-Type": "application/json" },
+        body: JSON.stringify({ name }),
+    });
+    if (!res.ok)
+        return undefined;
+    const data = await res.json();
+    const info = data.model_info ?? {};
+    const arch = info["general.architecture"];
+    if (arch) {
+        const ctx = info[`${arch}.context_length`];
+        if (typeof ctx === "number")
+            return ctx;
+    }
+    for (const [k, v] of Object.entries(info)) {
+        if (k.endsWith(".context_length") && typeof v === "number")
+            return v;
+    }
+    return undefined;
+}

package/dist/agent/providers/opencode.d.ts

@@ -0,0 +1,10 @@
+/**
+ * OpenCode Zen & Go providers — runtime model discovery via /models +
+ * models.dev metadata enrichment.
+ *
+ * Registers two providers:
+ *   - opencode     — Zen tier  (https://opencode.ai/zen/v1)
+ *   - opencode-go  — Go tier   (https://opencode.ai/zen/go/v1)
+ */
+import type { AgentContext } from "../host-types.js";
+export default function activate(ctx: AgentContext): void;

package/dist/agent/providers/opencode.js

@@ -0,0 +1,112 @@
+import { resolveApiKey } from "../../cli/auth/keys.js";
+const ZEN_BASE_URL = "https://opencode.ai/zen/v1";
+const GO_BASE_URL = "https://opencode.ai/zen/go/v1";
+const MODELS_DEV_ENDPOINT = "https://models.dev/api.json";
+const DEFAULT_CTX = 128_000;
+const DEFAULT_MAX_TOKENS = 16_384;
+const ZEN_FALLBACK = ["claude-sonnet-4-6"];
+const GO_FALLBACK = ["gpt-5.2"];
+// ── Helpers ──────────────────────────────────────────────────────
+async function fetchJson(url) {
+    const res = await fetch(url, {
+        headers: { Accept: "application/json" },
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    return res.json();
+}
+function findEntry(provider, id) {
+    const direct = provider?.models?.[id];
+    if (direct)
+        return direct;
+    if (!provider?.models)
+        return undefined;
+    return Object.values(provider.models).find((m) => m.id === id);
+}
+function resolveModel(id, meta) {
+    const raw = meta?.modalities?.input;
+    const modalities = Array.isArray(raw)
+        ? raw.filter((v) => v === "text" || v === "image")
+        : ["text"];
+    return {
+        id,
+        reasoning: meta?.reasoning ?? false,
+        contextWindow: (typeof meta?.limit?.context === "number" && meta.limit.context > 0)
+            ? meta.limit.context : DEFAULT_CTX,
+        maxTokens: (typeof meta?.limit?.output === "number" && meta.limit.output > 0)
+            ? meta.limit.output : DEFAULT_MAX_TOKENS,
+        modalities,
+    };
+}
+function reasoningParams(level) {
+    if (level === "off")
+        return { reasoning_effort: "none" };
+    return { reasoning_effort: level === "xhigh" ? "high" : level };
+}
+// ── Activation ───────────────────────────────────────────────────
+export default function activate(ctx) {
+    const apiKey = process.env.OPENCODE_API_KEY ??
+        resolveApiKey("opencode").key ?? undefined;
+    ctx.agent.providers.configure("opencode", { reasoningParams });
+    ctx.agent.providers.register({
+        id: "opencode", apiKey, baseURL: ZEN_BASE_URL,
+        defaultModel: ZEN_FALLBACK[0], models: ZEN_FALLBACK,
+        supportsReasoningEffort: true,
+    });
+    ctx.agent.providers.configure("opencode-go", { reasoningParams });
+    ctx.agent.providers.register({
+        id: "opencode-go", apiKey, baseURL: GO_BASE_URL,
+        defaultModel: GO_FALLBACK[0], models: GO_FALLBACK,
+        supportsReasoningEffort: true,
+    });
+    if (!apiKey)
+        return;
+    fetchModelsDev()
+        .then(async (md) => {
+        const zenIds = await fetchModelIds(ZEN_BASE_URL);
+        const goIds = await fetchModelIds(GO_BASE_URL);
+        const resolve = (ids, prov, fb) => (ids.length > 0 ? ids : fb).map((id) => resolveModel(id, findEntry(prov, id)));
+        const zen = resolve(zenIds, md?.opencode, ZEN_FALLBACK);
+        const go = resolve(goIds, md?.["opencode-go"], GO_FALLBACK);
+        ctx.agent.providers.register({
+            id: "opencode", apiKey, baseURL: ZEN_BASE_URL,
+            defaultModel: zen[0]?.id ?? ZEN_FALLBACK[0], models: zen,
+            supportsReasoningEffort: true,
+        });
+        ctx.agent.providers.register({
+            id: "opencode-go", apiKey, baseURL: GO_BASE_URL,
+            defaultModel: go[0]?.id ?? GO_FALLBACK[0], models: go,
+            supportsReasoningEffort: true,
+        });
+    })
+        .catch(() => { });
+}
+async function fetchModelsDev() {
+    try {
+        const payload = await fetchJson(MODELS_DEV_ENDPOINT);
+        if (!payload || typeof payload !== "object" || Array.isArray(payload))
+            return undefined;
+        return payload;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function fetchModelIds(baseURL) {
+    try {
+        const res = await fetch(`${baseURL}/models`, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok)
+            return [];
+        const payload = await res.json();
+        if (!Array.isArray(payload.data))
+            return [];
+        return [...new Set(payload.data.map((e) => e.id).filter(Boolean))];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/agent/providers/zai-coding-plan.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Z.AI Coding Plan — Zhipu AI's subscription GLM models for coding.
+ */
+import type { AgentContext } from "../host-types.js";
+export default function activate(ctx: AgentContext): void;

package/dist/agent/providers/zai-coding-plan.js

@@ -0,0 +1,26 @@
+import { resolveApiKey } from "../../cli/auth/keys.js";
+const BASE_URL = "https://api.z.ai/api/coding/paas/v4";
+const ID = "zai-coding-plan";
+const DEFAULT_MODELS = [
+    { id: "glm-5.1", reasoning: true, contextWindow: 200_000 },
+    { id: "glm-5-turbo", reasoning: true, contextWindow: 200_000 },
+    { id: "glm-4.7", reasoning: true, contextWindow: 204_800 },
+    { id: "glm-4.5-air", reasoning: true, contextWindow: 131_072 },
+];
+function buildReasoningParams(level, _model) {
+    if (level === "off")
+        return { thinking: { type: "disabled" } };
+    const effort = level === "xhigh" ? "high" : level;
+    return { thinking: { type: "enabled" }, reasoning_effort: effort };
+}
+export default function activate(ctx) {
+    const { key } = resolveApiKey(ID);
+    ctx.agent.providers.configure(ID, { reasoningParams: buildReasoningParams });
+    ctx.agent.providers.register({
+        id: ID,
+        apiKey: key ?? process.env.ZAI_API_KEY ?? process.env.ZHIPU_API_KEY,
+        baseURL: BASE_URL,
+        defaultModel: DEFAULT_MODELS[0].id,
+        models: DEFAULT_MODELS,
+    });
+}

package/dist/cli/args.js

@@ -53,8 +53,8 @@ export function parseArgs(argv, env = process.env) {
     let provider;
     let backend;
     let shell = env.SHELL || "/bin/bash";
-    let apiKey = env.OPENAI_API_KEY;
-    let baseURL = env.OPENAI_BASE_URL;
+    let apiKey;
+    let baseURL;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === "--model" && argv[i + 1]) {

package/examples/extensions/ads/index.ts

@@ -0,0 +1,695 @@
+/**
+ * ADS extension — NASA Astrophysics Data System tools for agent-sh.
+ *
+ * Provides four tools:
+ *   - ads_search:       Search ADS for papers
+ *   - ads_paper:        Fetch details of a specific paper by bibcode/DOI/arXiv ID
+ *   - ads_citations:    Find citing or referenced papers
+ *   - ads_download_pdf: Download paper PDFs
+ *
+ * Requires: ADS_API_TOKEN environment variable
+ *   Get one at https://ui.adsabs.harvard.edu/#user/settings/token
+ *
+ * Configuration (~/.agent-sh/settings.json):
+ *   {
+ *     "ads": { "pdfDownloadDir": "~/papers" }
+ *   }
+ */
+import type { AgentContext } from "agent-sh/types";
+import * as path from "path";
+import * as fs from "fs/promises";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+
+// ── Constants ────────────────────────────────────────────────────────
+
+const ADS_SEARCH_API = "https://api.adsabs.harvard.edu/v1/search/query";
+const ADS_EXPORT_API = "https://api.adsabs.harvard.edu/v1/export";
+const ADS_LINK_GATEWAY = "https://ui.adsabs.harvard.edu/link_gateway";
+
+const SEARCH_FIELDS = [
+  "bibcode", "title", "author", "abstract", "pubdate", "year",
+  "citation_count", "read_count", "doi", "identifier", "pub",
+  "arxiv_class", "keyword", "database", "doctype", "aff",
+  "volume", "issue", "page", "bibstem",
+].join(",");
+
+const PDF_SOURCES = {
+  publisher: "PUB_PDF",
+  ads: "ADS_PDF",
+  arxiv: "EPRINT_PDF",
+} as const;
+
+type PDFSource = keyof typeof PDF_SOURCES;
+
+const PDF_UA =
+  "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36";
+
+// ── Types ────────────────────────────────────────────────────────────
+
+interface ADSPaper {
+  bibcode: string;
+  title: string;
+  authors: string[];
+  affiliations: string[];
+  abstract: string;
+  pubdate: string;
+  year: string;
+  citationCount: number;
+  readCount: number;
+  doi: string[];
+  identifier: string[];
+  pub: string;
+  bibstem: string;
+  volume: string;
+  issue: string;
+  page: string;
+  arxivClass: string[];
+  keywords: string[];
+  database: string[];
+  doctype: string;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function parseDoc(doc: any): ADSPaper {
+  return {
+    bibcode: doc.bibcode ?? "",
+    title: Array.isArray(doc.title) ? doc.title.join(" ") : (doc.title ?? ""),
+    authors: Array.isArray(doc.author) ? doc.author : doc.author ? [doc.author] : [],
+    affiliations: Array.isArray(doc.aff) ? doc.aff : doc.aff ? [doc.aff] : [],
+    abstract: doc.abstract ?? "",
+    pubdate: doc.pubdate ?? "",
+    year: doc.year ?? "",
+    citationCount: doc.citation_count ?? 0,
+    readCount: doc.read_count ?? 0,
+    doi: Array.isArray(doc.doi) ? doc.doi : doc.doi ? [doc.doi] : [],
+    identifier: Array.isArray(doc.identifier) ? doc.identifier : doc.identifier ? [doc.identifier] : [],
+    pub: doc.pub ?? "",
+    bibstem: Array.isArray(doc.bibstem) ? doc.bibstem[0] ?? "" : (doc.bibstem ?? ""),
+    volume: doc.volume ?? "",
+    issue: doc.issue ?? "",
+    page: doc.page ?? "",
+    arxivClass: Array.isArray(doc.arxiv_class) ? doc.arxiv_class : doc.arxiv_class ? [doc.arxiv_class] : [],
+    keywords: Array.isArray(doc.keyword) ? doc.keyword : doc.keyword ? [doc.keyword] : [],
+    database: Array.isArray(doc.database) ? doc.database : doc.database ? [doc.database] : [],
+    doctype: doc.doctype ?? "",
+  };
+}
+
+function truncateAuthors(authors: string[], maxAuthors = 10): string {
+  if (authors.length <= maxAuthors) return authors.join("; ");
+  return `${authors.slice(0, maxAuthors).join("; ")}; ... +${authors.length - maxAuthors} more`;
+}
+
+function formatPaper(p: ADSPaper, index?: number): string {
+  const prefix = index !== undefined ? `[${index + 1}] ` : "";
+  const lines: string[] = [
+    `${prefix}${p.title}`,
+    `    Bibcode: ${p.bibcode}`,
+    `    Authors: ${truncateAuthors(p.authors)}`,
+    `    Published: ${p.pubdate}  Year: ${p.year}`,
+    `    Journal: ${p.pub}`,
+  ];
+  if (p.doi.length > 0) lines.push(`    DOI: ${p.doi.join(", ")}`);
+  if (p.arxivClass.length > 0) lines.push(`    arXiv: ${p.arxivClass.join(", ")}`);
+  if (p.keywords.length > 0) lines.push(`    Keywords: ${p.keywords.slice(0, 10).join(", ")}`);
+  lines.push(`    Citations: ${p.citationCount}  Reads: ${p.readCount}`);
+  lines.push(`    ADS URL: ${ADS_LINK_GATEWAY}/${p.bibcode}`);
+  if (p.abstract) lines.push(`    Abstract: ${p.abstract}`);
+  return lines.join("\n");
+}
+
+function formatPaperCompact(p: ADSPaper, index?: number): string {
+  const prefix = index !== undefined ? `[${index + 1}] ` : "";
+  const authorStr = p.authors.length > 0
+    ? p.authors.length === 1 ? p.authors[0] : `${p.authors[0]} et al.`
+    : "Unknown";
+  return `${prefix}${p.title}\n    ${p.bibcode} | ${authorStr} | ${p.year} | ${p.bibstem || p.pub} | ${p.citationCount} cit`;
+}
+
+function getToken(): string {
+  const token = process.env.ADS_API_TOKEN ?? "";
+  if (!token) {
+    throw new Error(
+      "ADS_API_TOKEN environment variable not set. " +
+      "Get a token from https://ui.adsabs.harvard.edu/#user/settings/token"
+    );
+  }
+  return token;
+}
+
+async function adsFetch(url: string, options?: RequestInit): Promise<any> {
+  const token = getToken();
+  const resp = await fetch(url, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      ...(options?.headers ?? {}),
+    },
+  });
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => "");
+    throw new Error(`ADS API error: ${resp.status} ${resp.statusText}${body ? ` - ${body}` : ""}`);
+  }
+  return resp.json();
+}
+
+function buildIdQuery(id: string): string {
+  const trimmed = id.trim();
+  if (trimmed.startsWith("10.") || trimmed.startsWith("doi:")) {
+    return `doi:"${trimmed.replace(/^doi:/, "")}"`;
+  } else if (trimmed.toLowerCase().startsWith("arxiv:") || /^\d{4}\.\d{4,5}/.test(trimmed)) {
+    return `arxiv:"${trimmed.replace(/^arxiv:/i, "")}"`;
+  }
+  return `bibcode:${trimmed}`;
+}
+
+async function resolveBibcode(id: string): Promise<{ bibcode: string; title: string }> {
+  const query = buildIdQuery(id);
+  const url = `${ADS_SEARCH_API}?q=${encodeURIComponent(query)}&fl=bibcode,title&rows=1`;
+  const data = await adsFetch(url);
+  const docs: any[] = (data.response ?? data).docs ?? [];
+  if (docs.length === 0) throw new Error(`Paper not found: ${id}`);
+  return {
+    bibcode: docs[0].bibcode ?? "",
+    title: Array.isArray(docs[0].title) ? docs[0].title.join(" ") : (docs[0].title ?? ""),
+  };
+}
+
+function buildSortParam(sortBy: string): string {
+  const map: Record<string, string> = {
+    relevance: "score desc",
+    date: "date desc",
+    citation_count: "citation_count desc",
+    read_count: "read_count desc",
+  };
+  return map[sortBy] ?? "score desc";
+}
+
+function isBibcode(id: string): boolean {
+  return /^\d{4}.{15}$/.test(id);
+}
+
+function bibcodeToFilename(bibcode: string): string {
+  return bibcode.replace(/\./g, "_");
+}
+
+function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+async function getPdfDownloadDir(): Promise<string> {
+  const settingsPath = path.join(homedir(), ".agent-sh", "settings.json");
+  try {
+    const raw = await fs.readFile(settingsPath, "utf8");
+    const settings = JSON.parse(raw);
+    const dir = settings?.ads?.pdfDownloadDir;
+    if (typeof dir === "string" && dir.length > 0) {
+      return dir.replace(/^~/, homedir());
+    }
+  } catch { /* settings may not exist */ }
+  // Default: ~/.agent-sh/papers
+  return path.join(homedir(), ".agent-sh", "papers");
+}
+
+async function fetchPDF(bibcode: string, sourceKey: PDFSource): Promise<ArrayBuffer> {
+  const url = `${ADS_LINK_GATEWAY}/${encodeURIComponent(bibcode)}/${PDF_SOURCES[sourceKey]}`;
+  const resp = await fetch(url, {
+    redirect: "follow",
+    headers: { "User-Agent": PDF_UA },
+  });
+
+  if (!resp.ok) {
+    throw new Error(`HTTP ${resp.status} ${resp.statusText} from ${sourceKey} source`);
+  }
+
+  const contentType = resp.headers.get("content-type") ?? "";
+  if (contentType.includes("text/html")) {
+    const body = await resp.text();
+    if (body.includes("CAPTCHA")) {
+      throw new Error(`CAPTCHA detected from ${sourceKey} source. Try a different source.`);
+    }
+    throw new Error(`Expected PDF but got HTML from ${sourceKey} source. The paper may be behind a paywall. Try source='arxiv'.`);
+  }
+  if (!contentType.includes("application/pdf")) {
+    throw new Error(`Unexpected Content-Type '${contentType}' from ${sourceKey} source.`);
+  }
+
+  return resp.arrayBuffer();
+}
+
+// ── Extension entry point ────────────────────────────────────────────
+
+export default function activate(ctx: AgentContext): void {
+  // Register the ADS query syntax skill — grouped with our tools in the system prompt
+  const skillPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "SKILL.md");
+  ctx.agent.registerSkill(
+    "ads",
+    "Full ADS query syntax reference and search strategy. Load before composing ADS queries — the tool descriptions only cover basic field prefixes.",
+    skillPath,
+  );
+
+  // ── ads_search ─────────────────────────────────────────────────────
+
+  ctx.agent.registerTool({
+    name: "ads_search",
+    displayName: "search",
+    description:
+      "Search astronomy/physics papers (ADS) — preferred over web_search for literature queries.\n" +
+      "Supports fielded syntax (title:, author:, year:, bibcode:, doi:), database filters, sort options.\n" +
+      "⚠️ Load the ads skill BEFORE using this tool for advanced syntax and search strategies.\n" +
+      "Requires ADS_API_TOKEN.",
+    input_schema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description:
+            'Search query. Supports fielded searches like "title:exoplanets", ' +
+            '"author:\\"Hubble, E\\"", "keyword:dark matter", "year:2023". ' +
+            'Unfielded terms search all metadata. Use quotes for phrases, +/- for inclusion/exclusion.',
+        },
+        database: {
+          type: "string",
+          enum: ["astronomy", "physics", "general"],
+          description: "Filter by ADS database. Default: searches all databases.",
+        },
+        doctype: {
+          type: "string",
+          enum: ["article", "eprint", "inproceedings", "proceedings", "inbook", "book", "phdthesis", "mastersthesis", "catalog", "software", "proposal"],
+          description: "Filter by document type.",
+        },
+        refereed: {
+          type: "boolean",
+          description: "Filter to only refereed (peer-reviewed) papers.",
+        },
+        year_from: {
+          type: "string",
+          description: "Start year for date range filter, e.g. '2020'.",
+        },
+        year_to: {
+          type: "string",
+          description: "End year for date range filter, e.g. '2024'.",
+        },
+        max_results: {
+          type: "number",
+          description: "Max papers to return (default 10, max 50).",
+        },
+        sort_by: {
+          type: "string",
+          enum: ["relevance", "date", "citation_count", "read_count"],
+          description: "Sort order (default: relevance).",
+        },
+        start: {
+          type: "number",
+          description: "Start index for pagination (default 0).",
+        },
+        detail: {
+          type: "string",
+          enum: ["compact", "full"],
+          description: "Output detail level. 'compact' (default): title, first author, year, bibcode, citations. 'full': includes abstract, all authors, keywords, DOI.",
+        },
+      },
+      required: ["query"],
+    },
+
+    async execute(args) {
+      const query = args.query as string;
+      const maxResults = Math.min((args.max_results as number) ?? 10, 50);
+      const start = (args.start as number) ?? 0;
+      const sort = buildSortParam((args.sort_by as string) ?? "relevance");
+      const detail = (args.detail as string) ?? "compact";
+
+      const fq: string[] = [];
+      if (args.database) fq.push(`database:${args.database}`);
+      if (args.doctype) fq.push(`doctype:${args.doctype}`);
+      if (args.refereed) fq.push("property:refereed");
+      if (args.year_from || args.year_to) {
+        fq.push(`year:[${args.year_from ?? "*"} TO ${args.year_to ?? "*"}]`);
+      }
+
+      const fqParam = fq.map(f => `&fq=${encodeURIComponent(f)}`).join("");
+      const url =
+        `${ADS_SEARCH_API}?q=${encodeURIComponent(query)}` +
+        `&fl=${SEARCH_FIELDS}&rows=${maxResults}&start=${start}` +
+        `&sort=${encodeURIComponent(sort)}${fqParam}`;
+
+      const data = await adsFetch(url);
+      const response = data.response ?? data;
+      const docs: any[] = response.docs ?? [];
+      const totalResults = response.numFound ?? 0;
+
+      if (docs.length === 0) {
+        return { content: `No papers found for query: ${query}`, exitCode: 0, isError: false };
+      }
+
+      const papers = docs.map(parseDoc);
+      const formatter = detail === "full" ? formatPaper : formatPaperCompact;
+      let text = `Found ${totalResults} papers (showing ${start + 1}-${start + papers.length}):\n`;
+      text += papers.map((p, i) => formatter(p, i)).join("\n\n");
+
+      const nextStart = start + papers.length;
+      if (nextStart < totalResults) {
+        text += `\n\n→ Use start=${nextStart} to see the next page of results.`;
+      }
+
+      return { content: text, exitCode: 0, isError: false };
+    },
+
+    getDisplayInfo(args) {
+      return { kind: "search" };
+    },
+
+    formatCall(args) {
+      const parts: string[] = [];
+      if (args.query) parts.push(String(args.query));
+      if (args.year_from || args.year_to) parts.push(`${args.year_from ?? "*"}–${args.year_to ?? "*"}`);
+      if (args.database) parts.push(`db:${args.database}`);
+      if (args.sort_by && args.sort_by !== "relevance") parts.push(`sort:${args.sort_by}`);
+      return parts.join("  ");
+    },
+  });
+
+  // ── ads_paper ──────────────────────────────────────────────────────
+
+  ctx.agent.registerTool({
+    name: "ads_paper",
+    displayName: "paper",
+    description:
+      "Fetch a paper's details from ADS by bibcode, DOI, or arXiv ID.\n" +
+      "Optional BibTeX return. ⚠️ Load the ads skill BEFORE using for field syntax help.\n" +
+      "Requires ADS_API_TOKEN.",
+    input_schema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description:
+            'Paper identifier: ADS bibcode (e.g. "2023ApJ...950L..12A"), ' +
+            'DOI (e.g. "10.3847/2041-8213/acb7e0"), or arXiv ID (e.g. "arXiv:2301.01234").',
+        },
+        bibtex: {
+          type: "boolean",
+          description: "Include BibTeX citation (default: false).",
+        },
+      },
+      required: ["id"],
+    },
+
+    async execute(args) {
+      const id = (args.id as string).trim();
+      const query = buildIdQuery(id);
+      const url = `${ADS_SEARCH_API}?q=${encodeURIComponent(query)}&fl=${SEARCH_FIELDS}&rows=1`;
+
+      const data = await adsFetch(url);
+      const docs: any[] = (data.response ?? data).docs ?? [];
+
+      if (docs.length === 0) {
+        return { content: `Paper not found: ${id}`, exitCode: 1, isError: true };
+      }
+
+      const paper = parseDoc(docs[0]);
+      let text = formatPaper(paper);
+
+      if (args.bibtex && paper.bibcode) {
+        try {
+          const exportData = await adsFetch(`${ADS_EXPORT_API}/bibtex`, {
+            method: "POST",
+            body: JSON.stringify({ bibcode: [paper.bibcode] }),
+          });
+          const bibtex = exportData.export ?? "";
+          if (bibtex) text += `\n\nBibTeX:\n${bibtex}`;
+        } catch {
+          text += "\n\n[Failed to fetch BibTeX]";
+        }
+      }
+
+      return { content: text, exitCode: 0, isError: false };
+    },
+
+    getDisplayInfo(args) {
+      return { kind: "read" };
+    },
+
+    formatCall(args) {
+      return String(args.id ?? "");
+    },
+  });
+
+  // ── ads_citations ──────────────────────────────────────────────────
+
+  ctx.agent.registerTool({
+    name: "ads_citations",
+    displayName: "citations",
+    description:
+      "List citations or references of an ADS bibcode.\n" +
+      "detail='compact'|'full'. ⚠️ Load the ads skill BEFORE using for syntax help.\n" +
+      "Requires ADS_API_TOKEN.",
+    input_schema: {
+      type: "object",
+      properties: {
+        bibcode: {
+          type: "string",
+          description: 'ADS bibcode of the paper, e.g. "2023ApJ...950L..12A".',
+        },
+        direction: {
+          type: "string",
+          enum: ["citations", "references"],
+          description: '"citations" = papers that cite this paper (default). "references" = papers this paper cites.',
+        },
+        max_results: {
+          type: "number",
+          description: "Max papers to return (default 10, max 50).",
+        },
+        sort_by: {
+          type: "string",
+          enum: ["date", "citation_count", "read_count"],
+          description: "Sort order (default: date).",
+        },
+        start: {
+          type: "number",
+          description: "Start index for pagination (default 0).",
+        },
+        detail: {
+          type: "string",
+          enum: ["compact", "full"],
+          description: "Output detail level. 'compact' (default) or 'full' with abstracts.",
+        },
+      },
+      required: ["bibcode"],
+    },
+
+    async execute(args) {
+      const bibcode = args.bibcode as string;
+      const direction = (args.direction as string) ?? "citations";
+      const maxResults = Math.min((args.max_results as number) ?? 10, 50);
+      const start = (args.start as number) ?? 0;
+      const sort = buildSortParam((args.sort_by as string) ?? "date");
+      const detail = (args.detail as string) ?? "compact";
+
+      const queryFunc = direction === "citations" ? "citations" : "references";
+      const query = `${queryFunc}(${bibcode})`;
+
+      const url =
+        `${ADS_SEARCH_API}?q=${encodeURIComponent(query)}` +
+        `&fl=${SEARCH_FIELDS}&rows=${maxResults}&start=${start}` +
+        `&sort=${encodeURIComponent(sort)}`;
+
+      const data = await adsFetch(url);
+      const response = data.response ?? data;
+      const docs: any[] = response.docs ?? [];
+      const totalResults = response.numFound ?? 0;
+
+      if (docs.length === 0) {
+        const label = direction === "citations" ? "citing" : "referenced by";
+        return { content: `No papers ${label} ${bibcode}`, exitCode: 0, isError: false };
+      }
+
+      const papers = docs.map(parseDoc);
+      const formatter = detail === "full" ? formatPaper : formatPaperCompact;
+      const dirLabel = direction === "citations" ? "citing papers" : "referenced papers";
+      let text = `Found ${totalResults} ${dirLabel} (showing ${start + 1}-${start + papers.length}):\n`;
+      text += papers.map((p, i) => formatter(p, i)).join("\n\n");
+
+      const nextStart = start + papers.length;
+      if (nextStart < totalResults) {
+        text += `\n\n→ Use start=${nextStart} to see the next page of results.`;
+      }
+
+      return { content: text, exitCode: 0, isError: false };
+    },
+
+    getDisplayInfo(args) {
+      return { kind: "search" };
+    },
+
+    formatCall(args) {
+      const dir = (args.direction as string) ?? "citations";
+      return `${args.bibcode} ${dir}`;
+    },
+  });
+
+  // ── ads_download_pdf ───────────────────────────────────────────────
+
+  ctx.agent.registerTool({
+    name: "ads_download_pdf",
+    displayName: "download",
+    description:
+      "Download a paper's PDF (bibcode/DOI/arXiv ID).\n" +
+      "Fallback: publisher → ADS → arXiv. ⚠️ Load the ads skill BEFORE using.\n" +
+      "Requires ADS_API_TOKEN.",
+    input_schema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description:
+            'Paper identifier: ADS bibcode (e.g. "2023ApJ...950L..12A"), ' +
+            'DOI (e.g. "10.3847/2041-8213/acb7e0"), or arXiv ID (e.g. "arXiv:2301.01234").',
+        },
+        output_path: {
+          type: "string",
+          description:
+            "File path to save the PDF. Defaults to ~/.agent-sh/papers/{bibcode}.pdf. " +
+            "If a directory path is given, saves as {dir}/{bibcode}.pdf.",
+        },
+        source: {
+          type: "string",
+          enum: ["auto", "publisher", "ads", "arxiv"],
+          description:
+            "Preferred PDF source. 'auto' (default) tries publisher → ADS → arXiv. " +
+            "'publisher' = PUB_PDF, 'ads' = ADS_PDF, 'arxiv' = EPRINT_PDF.",
+        },
+      },
+      required: ["id"],
+    },
+    modifiesFiles: true,
+
+    async execute(args) {
+      const sourceParam = (args.source as string) ?? "auto";
+      const trimmedId = (args.id as string).trim();
+      const idIsBibcode = isBibcode(trimmedId);
+      const downloadDir = await getPdfDownloadDir();
+
+      // Fast path: check if already downloaded (bibcode only)
+      if (!args.output_path && idIsBibcode) {
+        const candidatePath = downloadDir
+          ? path.join(downloadDir, `${bibcodeToFilename(trimmedId)}.pdf`)
+          : path.join(process.cwd(), `${bibcodeToFilename(trimmedId)}.pdf`);
+
+        try {
+          const stat = await fs.stat(candidatePath);
+          return {
+            content:
+              `PDF already exists: ${candidatePath}\n` +
+              `  Bibcode: ${trimmedId}\n` +
+              `  Size: ${formatFileSize(stat.size)}\n` +
+              `  Modified: ${stat.mtime.toISOString()}\n\n` +
+              `To re-download, delete the file first or specify a different output_path.`,
+            exitCode: 0,
+            isError: false,
+          };
+        } catch { /* not cached, continue */ }
+      }
+
+      // Resolve identifier to bibcode
+      let resolved: { bibcode: string; title: string };
+      try {
+        resolved = await resolveBibcode(args.id as string);
+      } catch {
+        return { content: `Paper not found: ${args.id}`, exitCode: 1, isError: true };
+      }
+
+      const { bibcode, title } = resolved;
+      const safeName = `${bibcodeToFilename(bibcode)}.pdf`;
+
+      let outputPath: string;
+      if (!args.output_path) {
+        outputPath = downloadDir
+          ? path.join(downloadDir, safeName)
+          : path.join(process.cwd(), safeName);
+      } else {
+        const op = args.output_path as string;
+        outputPath = (op.endsWith("/") || !path.extname(op))
+          ? path.join(op, safeName)
+          : op;
+      }
+
+      // Check if already exists (post-resolution)
+      try {
+        const stat = await fs.stat(outputPath);
+        return {
+          content:
+            `PDF already exists: ${outputPath}\n` +
+            `  Bibcode: ${bibcode}\n` +
+            `  Title: ${title}\n` +
+            `  Size: ${formatFileSize(stat.size)}\n` +
+            `  Modified: ${stat.mtime.toISOString()}\n\n` +
+            `To re-download, delete the file first or specify a different output_path.`,
+          exitCode: 0,
+          isError: false,
+        };
+      } catch { /* proceed with download */ }
+
+      // Try sources in order
+      const sourceOrder: PDFSource[] =
+        sourceParam === "auto"
+          ? ["publisher", "ads", "arxiv"]
+          : [sourceParam as PDFSource];
+
+      let pdfBuffer: ArrayBuffer | undefined;
+      let usedSource: PDFSource | undefined;
+      let lastError = "";
+
+      for (const src of sourceOrder) {
+        try {
+          pdfBuffer = await fetchPDF(bibcode, src);
+          usedSource = src;
+          break;
+        } catch (err: any) {
+          lastError = err.message ?? String(err);
+        }
+      }
+
+      if (!pdfBuffer || !usedSource) {
+        return {
+          content:
+            `Failed to download PDF for ${bibcode} (${title}).\n` +
+            `Tried sources: ${sourceOrder.join(" → ")}.\n` +
+            `Last error: ${lastError}\n\n` +
+            `Try downloading manually: ${ADS_LINK_GATEWAY}/${bibcode}/EPRINT_PDF`,
+          exitCode: 1,
+          isError: true,
+        };
+      }
+
+      await fs.mkdir(path.dirname(outputPath), { recursive: true });
+      await fs.writeFile(outputPath, Buffer.from(pdfBuffer));
+
+      const sourceLabel = { publisher: "publisher", ads: "ADS", arxiv: "arXiv" }[usedSource];
+      return {
+        content:
+          `Downloaded PDF for: ${title}\n` +
+          `  Bibcode: ${bibcode}\n` +
+          `  Source: ${sourceLabel}\n` +
+          `  Saved to: ${outputPath}\n` +
+          `  Size: ${formatFileSize(pdfBuffer.byteLength)}`,
+        exitCode: 0,
+        isError: false,
+      };
+    },
+
+    getDisplayInfo(args) {
+      return { kind: "write" };
+    },
+
+    formatCall(args) {
+      return String(args.id ?? "");
+    },
+  });
+}

package/examples/extensions/ash-scheme/index.ts

@@ -319,6 +319,36 @@ function format(v: unknown): string {
 }
 
 // ── evaluator ─────────────────────────────────────────────────────
+// LIPS 0.20.x has no character type, so a `#\…` literal reads as an unbound
+// symbol. preprocessSchemeSource expands each to a 1-char string instead.
+const NAMED_CHARS: Record<string, string> = {
+  newline: "\n", linefeed: "\n", nl: "\n",
+  space: " ", tab: "\t", return: "\r",
+  null: "\u0000", nul: "\u0000",
+  delete: "\u007f", rubout: "\u007f",
+  escape: "\u001b", altmode: "\u001b",
+  backspace: "\u0008", alarm: "\u0007", page: "\u000c",
+};
+
+// The char after `#\` as a 1-char string + its span, or null for an unknown
+// multi-char name (left untranslated so it surfaces as an error).
+function resolveCharLiteral(source: string, start: number): { ch: string; span: number } | null {
+  let j = start;
+  while (j < source.length && /[A-Za-z0-9]/.test(source[j])) j++;
+  const run = source.slice(start, j);
+  if (run.length <= 1) {
+    const ch = source[start];
+    return ch === undefined ? null : { ch, span: 1 };
+  }
+  const hex = /^[xX]([0-9a-fA-F]+)$/.exec(run);
+  if (hex) {
+    const cp = parseInt(hex[1], 16);
+    if (cp >= 0 && cp <= 0x10ffff) return { ch: String.fromCodePoint(cp), span: run.length };
+  }
+  const named = NAMED_CHARS[run.toLowerCase()];
+  return named === undefined ? null : { ch: named, span: run.length };
+}
+
 // LIPS implements string literals via JSON.parse, which rejects backslash
 // escapes outside JSON's tiny set (\" \\ \/ \b \f \n \r \t \uXXXX). Models
 // routinely write \s \w \d etc. in regex strings. Pre-process: promote any
@@ -339,6 +369,14 @@ function preprocessSchemeSource(source: string): string {
     if (!inStr) {
       if (c === ";") { inComment = true; out += c; continue; }
       if (c === '"') { inStr = true; out += c; continue; }
+      if (c === "#" && source[i + 1] === "\\") {
+        const lit = resolveCharLiteral(source, i + 2);
+        if (lit) {
+          out += JSON.stringify(lit.ch);
+          i += 1 + lit.span; // skip '\' + the name/char; loop's i++ skips '#'
+          continue;
+        }
+      }
       out += c;
       continue;
     }
@@ -518,6 +556,11 @@ async function evaluate(env: any, source: string, timeoutMs: number) {
       msg = formatParenDiagnostic(source, msg);
     } else if (/Bad escaped character in JSON|Unexpected.*JSON|JSON at position/.test(msg)) {
       msg = formatStringEscapeDiagnostic(source, msg);
+    } else if (msg.includes("Unbound variable `#\\")) {
+      msg += "\n  This runtime has no character type — characters are 1-char strings." +
+        " `#\\newline`, `#\\space`, `#\\tab`, `#\\return`, `#\\xNN`, and `#\\<char>`" +
+        " are accepted (read as strings); other `#\\<name>` forms are not." +
+        " Use a string literal instead, e.g. \"\\n\".";
     }
     return { ok: false as const, error: msg };
   } finally {
@@ -1370,6 +1413,25 @@ function installStdShims(env: any): void {
   });
   defineIfMissing("char-upcase",   (c: any) => String(c).toUpperCase());
   defineIfMissing("char-downcase", (c: any) => String(c).toLowerCase());
+  // Characters are 1-char strings; char? therefore can't tell a char from a
+  // length-1 string.
+  const charStr = (c: any) => (typeof c === "string" ? c : String(c));
+  const codeOf = (c: any) => charStr(c).codePointAt(0) ?? 0;
+  defineIfMissing("char->integer", (c: any) => codeOf(c));
+  defineIfMissing("integer->char", (n: any) => String.fromCodePoint(Math.max(0, Math.floor(Number(n) || 0))));
+  defineIfMissing("char?", (x: any) => typeof x === "string" && Array.from(x).length === 1);
+  defineIfMissing("char=?",  (a: any, b: any) => charStr(a) === charStr(b));
+  defineIfMissing("char<?",  (a: any, b: any) => codeOf(a) <  codeOf(b));
+  defineIfMissing("char>?",  (a: any, b: any) => codeOf(a) >  codeOf(b));
+  defineIfMissing("char<=?", (a: any, b: any) => codeOf(a) <= codeOf(b));
+  defineIfMissing("char>=?", (a: any, b: any) => codeOf(a) >= codeOf(b));
+  defineIfMissing("char-ci=?", (a: any, b: any) => charStr(a).toLowerCase() === charStr(b).toLowerCase());
+  defineIfMissing("char-alphabetic?", (c: any) => /^\p{L}$/u.test(charStr(c)));
+  defineIfMissing("char-numeric?",    (c: any) => /^\p{Nd}$/u.test(charStr(c)));
+  defineIfMissing("char-whitespace?", (c: any) => /^\s$/.test(charStr(c)));
+  defineIfMissing("char-upper-case?", (c: any) => { const s = charStr(c); return s.length === 1 && s === s.toUpperCase() && s !== s.toLowerCase(); });
+  defineIfMissing("char-lower-case?", (c: any) => { const s = charStr(c); return s.length === 1 && s === s.toLowerCase() && s !== s.toUpperCase(); });
+  defineIfMissing("digit-value", (c: any) => { const s = charStr(c); return /^[0-9]$/.test(s) ? Number(s) : false; });
   defineIfMissing("string-normalize-spaces", (s: any, sep?: any, repl?: any) => {
     const str = String(s).trim();
     const splitOn = sep === undefined ? /\s+/ : (sep instanceof RegExp ? sep : new RegExp(String(sep)));
@@ -1500,9 +1562,9 @@ function installStdShims(env: any): void {
 }
 
 // Canonical names we claim coverage for. R = R7RS small base; S = SRFI-1;
-// K = Racket racket/base/list/string/format. Continuations, ports, bytevectors,
-// and char predicates are intentionally omitted — they'd be misleading
-// "coverage" without real functionality.
+// K = Racket racket/base/list/string/format. Continuations, ports, and
+// bytevectors are intentionally omitted — they'd be misleading "coverage"
+// without real functionality. Characters are modeled as 1-char strings.
 const COVERAGE_CHECKLIST: string[] = [
   // R7RS § 6.1 equivalence
   "eq?", "eqv?", "equal?",
@@ -1584,6 +1646,10 @@ const COVERAGE_CHECKLIST: string[] = [
   // Racket strings & chars (gaps)
   "string-titlecase", "string-pad", "string-pad-right",
   "char-upcase", "char-downcase",
+  "char->integer", "integer->char", "char?",
+  "char=?", "char<?", "char>?", "char<=?", "char>=?", "char-ci=?",
+  "char-alphabetic?", "char-numeric?", "char-whitespace?",
+  "char-upper-case?", "char-lower-case?", "digit-value",
   "string-normalize-spaces", "build-string",
   // Racket hash
   "make-hash", "hash", "hash?", "hash-ref", "hash-set!", "hash-set",
@@ -1841,6 +1907,10 @@ function installBindings(
   env.set("string-contains", stringContains);
   env.set("string-append", (...parts: unknown[]) =>
     parts.map((p) => (p === undefined || p === null ? "" : String(p))).join(""));
+  // LIPS' native `string` returns only its first argument; override to actually
+  // concatenate (chars are 1-char strings here, so that's the right semantics).
+  env.set("string", (...parts: unknown[]) =>
+    parts.map((p) => (p === undefined || p === null ? "" : String(p))).join(""));
   env.set("number->string", (n: unknown) => String(n));
   env.set("string->number", (s: unknown) => {
     if (typeof s !== "string") return false;
@@ -1949,6 +2019,10 @@ const DESCRIPTION = [
   "  - R7RS truthy semantics: anything that isn't `#f` is true. `(if str …)`,",
   "    `(if 0 …)`, `(if '() …)` all take the then-branch.",
   "  - `#t`/`#f` work as expected. `equal?`, `eq?`, `eqv?`, `string=?` all work.",
+  "  - Characters are 1-char strings (no separate char type). `#\\newline`,",
+  "    `#\\space`, `#\\tab`, `#\\return`, `#\\xNN`, and `#\\<char>` literals read as",
+  "    the equivalent string; `char->integer`/`integer->char`/`char?`/`char=?`/",
+  "    `char-whitespace?` etc. operate on them. A bare newline is just \"\\n\".",
   "  - SRFI-1: `member`, `assq`/`assv`/`assoc`, `delete-duplicates`, `first`",
   "    through `fifth`, `last`, `take`, `drop`, `iota`, `any`, `every`, `count`,",
   "    `find`, `filter-map`, `append-map`, `concatenate`, `partition`, `remove`,",

package/examples/extensions/ashi/src/cli.ts

@@ -36,8 +36,8 @@ import * as path from "node:path";
 
 function parseArgs(argv: string[]): AppConfig & { extensions?: string[]; continueLast: boolean } {
   let model: string | undefined;
-  let apiKey: string | undefined = process.env.OPENAI_API_KEY ?? process.env.OPENROUTER_API_KEY;
-  let baseURL: string | undefined = process.env.OPENAI_BASE_URL;
+  let apiKey: string | undefined;
+  let baseURL: string | undefined;
   let provider: string | undefined;
   let backend: string | undefined;
   let continueLast = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.14.9",
+  "version": "0.14.10",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "workspaces": [