@theokit/sdk-tools 0.27.5 → 0.28.0

package/dist/github-link-preview.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/github-link-preview.ts"],"names":[],"mappings":"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","file":"github-link-preview.js","sourcesContent":["/**\n * `github_link_preview` — turn a github.com issue, pull request or repository URL into its title,\n * state and summary.\n *\n * The model's URL is parsed, never fetched: owner, repository and number are validated against\n * GitHub's own name charset and the request always goes to a fixed `https://api.github.com`\n * endpoint built from those parts (ADR D1). Redirects are refused, so a response can never choose\n * the next host or carry the bearer token elsewhere (ADR D2).\n *\n * Return shape (always a JSON string):\n *   - `{ ok: true, kind, url, title, state, summary }`\n *   - `{ ok: false, error: 'unsupported_url' | 'redirect_blocked' | 'not_found' | 'rate_limited' |\n *        'upstream_error' | 'timeout' | 'fetch_failed' | 'invalid_response', url, ... }`\n */\n\nimport type { CustomTool } from \"@theokit/sdk\";\n\nimport { Tool } from \"@theokit/sdk\";\nimport { z } from \"zod\";\n\nconst API_BASE = \"https://api.github.com\";\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst DEFAULT_MAX_SUMMARY_CHARS = 500;\nconst MAX_BODY_BYTES = 1_048_576;\nconst GITHUB_HOSTS = new Set([\"github.com\", \"www.github.com\"]);\nconst OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;\nconst REPO_PATTERN = /^[A-Za-z0-9._-]{1,100}$/;\nconst NUMBER_PATTERN = /^[1-9][0-9]{0,9}$/;\n\n/** What a previewed GitHub URL points at, taken from its path. */\nexport type GithubLinkKind = \"repository\" | \"issue\" | \"pull_request\";\n\n/** Options for {@link createGithubLinkPreviewTool}; every one is optional. */\nexport interface CreateGithubLinkPreviewToolOptions {\n  /** Fetch implementation with the global `fetch` signature (injectable for tests). */\n  fetchImpl?: typeof fetch;\n  /** Optional GitHub token, sent as `Authorization: Bearer` to api.github.com only. */\n  token?: string;\n  /** Name exposed to the model. Default `github_link_preview`. */\n  name?: string;\n  /** Description exposed to the model. */\n  description?: string;\n  /** Timeout covering the request and the body read, in ms. Default 10000. */\n  timeoutMs?: number;\n  /** Longest summary returned, in code points. Default 500. */\n  maxSummaryChars?: number;\n  /** Clock for `retry_after_seconds` (injectable for tests). Default `Date.now`. */\n  now?: () => number;\n}\n\n/** The JSON the `github_link_preview` tool returns: a preview, or a typed failure. */\nexport type GithubLinkPreviewResult =\n  | {\n      ok: true;\n      kind: GithubLinkKind;\n      url: string;\n      title: string;\n      state: string;\n      summary: string;\n    }\n  | {\n      ok: false;\n      error:\n        | \"unsupported_url\"\n        | \"redirect_blocked\"\n        | \"not_found\"\n        | \"rate_limited\"\n        | \"upstream_error\"\n        | \"timeout\"\n        | \"fetch_failed\"\n        | \"invalid_response\";\n      url: string;\n      status?: number;\n      retry_after_seconds?: number;\n      timeout_ms?: number;\n      error_name?: string;\n    };\n\ninterface GithubTarget {\n  kind: GithubLinkKind;\n  owner: string;\n  repo: string;\n  number?: string;\n}\n\ninterface Settings {\n  fetchImpl: typeof fetch;\n  headers: Record<string, string>;\n  timeoutMs: number;\n  maxSummaryChars: number;\n  now: () => number;\n}\n\ntype Failure = Extract<GithubLinkPreviewResult, { ok: false }>;\ntype FailureError = Failure[\"error\"];\n\nclass PreviewFailure extends Error {\n  constructor(\n    readonly error: FailureError,\n    readonly extra: Omit<Failure, \"ok\" | \"error\" | \"url\"> = {},\n  ) {\n    super(error);\n  }\n}\n\nfunction requirePositiveInteger(name: string, value: number): number {\n  if (!Number.isInteger(value) || value <= 0) {\n    throw new RangeError(\n      `createGithubLinkPreviewTool: ${name} must be a positive integer, got ${value}`,\n    );\n  }\n  return value;\n}\n\nfunction hasControlCharacter(text: string): boolean {\n  return Array.from(text).some((char) => {\n    const code = char.charCodeAt(0);\n    return code < 0x20 || code === 0x7f;\n  });\n}\n\nfunction requireValidToken(token: string): string {\n  if (token.trim() === \"\" || hasControlCharacter(token)) {\n    throw new RangeError(\n      \"createGithubLinkPreviewTool: token must be non-blank and free of control characters\",\n    );\n  }\n  return token;\n}\n\nfunction buildHeaders(token: string | undefined): Record<string, string> {\n  const headers: Record<string, string> = {\n    accept: \"application/vnd.github+json\",\n    \"user-agent\": \"theokit-sdk-tools\",\n    \"x-github-api-version\": \"2022-11-28\",\n  };\n  if (token !== undefined) headers.authorization = `Bearer ${token}`;\n  return headers;\n}\n\nfunction isGithubOrigin(parsed: URL): boolean {\n  return (\n    parsed.protocol === \"https:\" &&\n    GITHUB_HOSTS.has(parsed.hostname) &&\n    parsed.username === \"\" &&\n    parsed.password === \"\" &&\n    parsed.port === \"\"\n  );\n}\n\nconst SECTION_KINDS: Readonly<Record<string, GithubLinkKind>> = {\n  issues: \"issue\",\n  pull: \"pull_request\",\n};\n\nfunction isValidRepository(owner: string, repo: string): boolean {\n  return OWNER_PATTERN.test(owner) && REPO_PATTERN.test(repo) && repo !== \".\" && repo !== \"..\";\n}\n\nfunction numberedTarget(owner: string, repo: string, segments: string[]): GithubTarget | undefined {\n  const [, , section = \"\", number = \"\"] = segments;\n  const kind = Object.hasOwn(SECTION_KINDS, section) ? SECTION_KINDS[section] : undefined;\n  if (segments.length !== 4 || kind === undefined || !NUMBER_PATTERN.test(number)) return undefined;\n  return { kind, owner, repo, number };\n}\n\nfunction targetFromSegments(segments: string[]): GithubTarget | undefined {\n  const [owner = \"\", repo = \"\"] = segments;\n  if (!isValidRepository(owner, repo)) return undefined;\n  if (segments.length === 2) return { kind: \"repository\", owner, repo };\n  return numberedTarget(owner, repo, segments);\n}\n\nfunction parseGithubUrl(url: string): GithubTarget | undefined {\n  let parsed: URL;\n  try {\n    parsed = new URL(url);\n  } catch {\n    return undefined;\n  }\n  if (!isGithubOrigin(parsed)) return undefined;\n  const segments = parsed.pathname.split(\"/\").slice(1);\n  if (segments.at(-1) === \"\") segments.pop();\n  return targetFromSegments(segments);\n}\n\nfunction apiUrlFor(target: GithubTarget): string {\n  const base = `${API_BASE}/repos/${target.owner}/${target.repo}`;\n  if (target.kind === \"issue\") return `${base}/issues/${target.number}`;\n  if (target.kind === \"pull_request\") return `${base}/pulls/${target.number}`;\n  return base;\n}\n\nfunction canonicalUrlFor(target: GithubTarget): string {\n  const base = `https://github.com/${target.owner}/${target.repo}`;\n  if (target.kind === \"issue\") return `${base}/issues/${target.number}`;\n  if (target.kind === \"pull_request\") return `${base}/pull/${target.number}`;\n  return base;\n}\n\n// `retry-after` is read as delta-seconds only; an HTTP-date value falls through to the epoch reset.\nfunction retryAfterSeconds(headers: Headers, nowMs: number): number | undefined {\n  const retryAfter = Number(headers.get(\"retry-after\") ?? Number.NaN);\n  if (Number.isFinite(retryAfter)) return Math.max(0, Math.ceil(retryAfter));\n  const reset = Number(headers.get(\"x-ratelimit-reset\") ?? Number.NaN);\n  if (Number.isFinite(reset)) return Math.max(0, Math.ceil(reset - nowMs / 1000));\n  return undefined;\n}\n\nfunction isRateLimited(response: Response): boolean {\n  if (response.status !== 403 && response.status !== 429) return false;\n  return (\n    response.headers.get(\"x-ratelimit-remaining\") === \"0\" || response.headers.has(\"retry-after\")\n  );\n}\n\nfunction checkStatus(response: Response, nowMs: number): void {\n  const { status } = response;\n  if (status >= 200 && status < 300) return;\n  if (status >= 300 && status < 400) throw new PreviewFailure(\"redirect_blocked\", { status });\n  if (status === 404) throw new PreviewFailure(\"not_found\", { status });\n  if (isRateLimited(response)) {\n    const retry = retryAfterSeconds(response.headers, nowMs);\n    throw new PreviewFailure(\"rate_limited\", {\n      status,\n      ...(retry === undefined ? {} : { retry_after_seconds: retry }),\n    });\n  }\n  throw new PreviewFailure(\"upstream_error\", { status });\n}\n\nasync function readCappedJson(response: Response): Promise<unknown> {\n  if (Number(response.headers.get(\"content-length\") ?? 0) > MAX_BODY_BYTES) {\n    throw new PreviewFailure(\"invalid_response\");\n  }\n  const text = await response.text();\n  if (Buffer.byteLength(text, \"utf8\") > MAX_BODY_BYTES) {\n    throw new PreviewFailure(\"invalid_response\");\n  }\n  try {\n    return JSON.parse(text) as unknown;\n  } catch {\n    throw new PreviewFailure(\"invalid_response\");\n  }\n}\n\nfunction cutCodePoints(text: unknown, max: number): string {\n  if (typeof text !== \"string\") return \"\";\n  return Array.from(text).slice(0, max).join(\"\");\n}\n\nfunction stateOf(target: GithubTarget, body: Record<string, unknown>): string {\n  if (target.kind === \"repository\") return body.archived === true ? \"archived\" : \"active\";\n  if (target.kind === \"pull_request\" && body.merged === true) return \"merged\";\n  if (typeof body.state !== \"string\") throw new PreviewFailure(\"invalid_response\");\n  return body.state;\n}\n\nfunction mapPreview(\n  target: GithubTarget,\n  body: unknown,\n  maxSummaryChars: number,\n): GithubLinkPreviewResult {\n  if (typeof body !== \"object\" || body === null || Array.isArray(body)) {\n    throw new PreviewFailure(\"invalid_response\");\n  }\n  const record = body as Record<string, unknown>;\n  const isRepository = target.kind === \"repository\";\n  const title = isRepository ? record.full_name : record.title;\n  if (typeof title !== \"string\") throw new PreviewFailure(\"invalid_response\");\n  return {\n    ok: true,\n    kind: target.kind,\n    url: canonicalUrlFor(target),\n    title,\n    state: stateOf(target, record),\n    summary: cutCodePoints(isRepository ? record.description : record.body, maxSummaryChars),\n  };\n}\n\nfunction failureFor(err: unknown, timeoutMs: number): PreviewFailure {\n  if (err instanceof PreviewFailure) return err;\n  const name = (err as { name?: unknown } | null)?.name;\n  if (name === \"AbortError\" || name === \"TimeoutError\") {\n    return new PreviewFailure(\"timeout\", { timeout_ms: timeoutMs });\n  }\n  return new PreviewFailure(\"fetch_failed\", {\n    error_name: typeof name === \"string\" ? name : \"unknown\",\n  });\n}\n\nasync function fetchPreview(\n  target: GithubTarget,\n  settings: Settings,\n): Promise<GithubLinkPreviewResult> {\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), settings.timeoutMs);\n  try {\n    const response = await settings.fetchImpl(apiUrlFor(target), {\n      method: \"GET\",\n      redirect: \"manual\",\n      signal: controller.signal,\n      headers: settings.headers,\n    });\n    checkStatus(response, settings.now());\n    const body = await readCappedJson(response);\n    return mapPreview(target, body, settings.maxSummaryChars);\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\nasync function preview(url: string, settings: Settings): Promise<GithubLinkPreviewResult> {\n  const target = parseGithubUrl(url);\n  if (target === undefined) return { ok: false, error: \"unsupported_url\", url };\n  try {\n    return await fetchPreview(target, settings);\n  } catch (err) {\n    const failure = failureFor(err, settings.timeoutMs);\n    return { ok: false, error: failure.error, url, ...failure.extra };\n  }\n}\n\n/**\n * Build the `github_link_preview` tool. Every option is optional: `createGithubLinkPreviewTool()`\n * previews public objects anonymously with a 10-second timeout and a 500-character summary.\n *\n * Only three URL shapes are accepted: `https://github.com/<owner>/<repo>`,\n * `.../issues/<n>` and `.../pull/<n>` (also on `www.github.com`; a trailing slash, query or\n * fragment is ignored). Anything else is `unsupported_url` and makes no request.\n *\n * Throws `RangeError` at construction for a non-positive or fractional `timeoutMs` or\n * `maxSummaryChars`, and for a blank token or one with a control character. Every failure after\n * construction is a typed `{ ok: false, error }` result, never a throw. The token is never\n * echoed: error bodies are not returned, and `fetch_failed` carries only the error's name.\n */\nexport function createGithubLinkPreviewTool(opts?: CreateGithubLinkPreviewToolOptions): CustomTool {\n  const settings: Settings = {\n    fetchImpl: opts?.fetchImpl ?? fetch,\n    headers: buildHeaders(opts?.token === undefined ? undefined : requireValidToken(opts.token)),\n    timeoutMs: requirePositiveInteger(\"timeoutMs\", opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS),\n    maxSummaryChars: requirePositiveInteger(\n      \"maxSummaryChars\",\n      opts?.maxSummaryChars ?? DEFAULT_MAX_SUMMARY_CHARS,\n    ),\n    now: opts?.now ?? Date.now,\n  };\n\n  return Tool.create({\n    name: opts?.name ?? \"github_link_preview\",\n    description:\n      opts?.description ??\n      \"Preview a GitHub issue, pull request or repository from its github.com URL. Returns \" +\n        \"{ ok, kind, url, title, state, summary } where state is open/closed/merged for issues and \" +\n        \"pull requests and active/archived for repositories, or { ok: false, error }. Only \" +\n        \"https://github.com/<owner>/<repo>, .../issues/<n> and .../pull/<n> are accepted.\",\n    inputSchema: z.object({\n      url: z.string().min(1).describe(\"A github.com repository, issue or pull request URL.\"),\n    }),\n    handler: async ({ url }) => JSON.stringify(await preview(url, settings)),\n  });\n}\n"]}

package/dist/index.cjs

@@ -2461,6 +2461,123 @@ function formatResult(result, timeoutMs) {
     exit_code: result.exitCode
   });
 }
+var AUDIO_EXTENSIONS = /* @__PURE__ */ new Map([
+  ["audio/mpeg", "mp3"],
+  ["audio/wav", "wav"],
+  ["audio/x-wav", "wav"],
+  ["audio/ogg", "ogg"],
+  ["audio/opus", "opus"],
+  ["audio/flac", "flac"],
+  ["audio/aac", "aac"],
+  ["audio/webm", "webm"]
+]);
+var DEFAULT_MAX_TEXT_CHARS = 4096;
+var DEFAULT_MAX_AUDIO_BYTES = 10 * 1024 * 1024;
+var STEM_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+var json = (result) => JSON.stringify(result);
+var errorMessage = (err) => err instanceof Error ? err.message : String(err);
+var errorCode = (err) => err.code ?? "unknown";
+function requirePositiveInteger(name, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RangeError(
+      `createTextToSpeechTool: ${name} must be a positive integer, got ${value}`
+    );
+  }
+  return value;
+}
+function defaultStem(text) {
+  return `speech-${crypto.createHash("sha256").update(text).digest("hex").slice(0, 8)}`;
+}
+function refusePath(relativeStem, stem, projectRoot) {
+  if (!STEM_PATTERN.test(stem) || isForbiddenAtAnyDepth(relativeStem)) {
+    return json({ ok: false, error: "path_traversal", path: relativeStem });
+  }
+  return checkPathScope(relativeStem, projectRoot);
+}
+async function synthesizeSafely(synthesize, text) {
+  try {
+    const value = await synthesize(text);
+    if (!(value?.audio instanceof Uint8Array) || typeof value.mimeType !== "string") {
+      return { ok: false, error: "synthesis_failed", message: "provider returned no audio" };
+    }
+    return { audio: value.audio, mimeType: value.mimeType };
+  } catch (err) {
+    return { ok: false, error: "synthesis_failed", message: errorMessage(err) };
+  }
+}
+function checkAudio({ audio, mimeType }, maxAudioBytes) {
+  const extension = AUDIO_EXTENSIONS.get(mimeType);
+  if (extension === void 0)
+    return { ok: false, error: "unsupported_audio_type", mime_type: mimeType };
+  if (audio.length === 0) return { ok: false, error: "empty_audio" };
+  if (audio.length > maxAudioBytes) {
+    return { ok: false, error: "audio_too_large", bytes: audio.length, max_bytes: maxAudioBytes };
+  }
+  return { extension };
+}
+async function writeAtomic(target, audio) {
+  const temp = `${path.dirname(target)}/.${path.basename(target)}.${crypto.randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await promises.writeFile(temp, audio, { flag: "wx", mode: 384 });
+    await promises.rename(temp, target);
+  } catch (err) {
+    await promises.rm(temp, { force: true });
+    throw err;
+  }
+}
+async function saveClip(projectRoot, outputDir, relativePath2, { audio, mimeType }) {
+  const target = pathSafety.safePathJoin(projectRoot, relativePath2);
+  try {
+    await promises.mkdir(path.dirname(target), { recursive: true });
+    const refused = checkPathScope(outputDir, projectRoot);
+    if (refused !== null) return refused;
+    await writeAtomic(target, audio);
+    return json({ ok: true, path: relativePath2, mime_type: mimeType, bytes: audio.length });
+  } catch (err) {
+    return json({ ok: false, error: "write_failed", message: errorCode(err) });
+  }
+}
+function createTextToSpeechTool(opts) {
+  const { synthesize, projectRoot } = opts;
+  const outputDir = path.posix.normalize((opts.outputDir ?? "audio").replace(/\\/g, "/"));
+  const maxTextChars = requirePositiveInteger(
+    "maxTextChars",
+    opts.maxTextChars ?? DEFAULT_MAX_TEXT_CHARS
+  );
+  const maxAudioBytes = requirePositiveInteger(
+    "maxAudioBytes",
+    opts.maxAudioBytes ?? DEFAULT_MAX_AUDIO_BYTES
+  );
+  return sdk.Tool.create({
+    name: opts.name ?? "text_to_speech",
+    description: opts.description ?? "Turn text into spoken audio and save it as a file in the project. Use when the user asks for speech, a voice reply or an audio clip. Returns { ok, path, mime_type, bytes } with the path relative to the project root, or { ok: false, error }. The speech provider is injected by the consumer.",
+    inputSchema: zod.z.object({
+      text: zod.z.string().min(1).describe("The text to speak."),
+      filename: zod.z.string().optional().describe(
+        "File name without extension (letters, digits, '.', '_', '-'). Default: derived from the text."
+      )
+    }),
+    handler: async ({ text, filename }) => {
+      if (text.length > maxTextChars) {
+        return json({
+          ok: false,
+          error: "text_too_large",
+          chars: text.length,
+          max_chars: maxTextChars
+        });
+      }
+      const stem = filename ?? defaultStem(text);
+      const refused = refusePath(path.posix.join(outputDir, stem), stem, projectRoot);
+      if (refused !== null) return refused;
+      const synthesized = await synthesizeSafely(synthesize, text);
+      if ("ok" in synthesized) return json(synthesized);
+      const checked = checkAudio(synthesized, maxAudioBytes);
+      if ("ok" in checked) return json(checked);
+      const relativePath2 = path.posix.join(outputDir, `${stem}.${checked.extension}`);
+      return saveClip(projectRoot, outputDir, relativePath2, synthesized);
+    }
+  });
+}
 
 // src/todo-plan-nodes.ts
 function todoItemsToPlanNodes(items) {
@@ -2663,7 +2780,7 @@ var MEDIA_TYPES = /* @__PURE__ */ new Map([
   [".webp", "image/webp"]
 ]);
 var DEFAULT_MAX_IMAGE_BYTES = 5 * 1024 * 1024;
-var json = (result) => JSON.stringify(result);
+var json2 = (result) => JSON.stringify(result);
 function createViewImageTool(options) {
   const { projectRoot } = options;
   const maxBytes = options.maxBytes ?? DEFAULT_MAX_IMAGE_BYTES;
@@ -2677,11 +2794,11 @@ function createViewImageTool(options) {
       const refused = checkPathScope(input.path, projectRoot);
       if (refused !== null) return refused;
       if (isForbiddenAtAnyDepth(input.path)) {
-        return json({ ok: false, error: "path_traversal", path: input.path });
+        return json2({ ok: false, error: "path_traversal", path: input.path });
       }
       const mediaType = MEDIA_TYPES.get(path.extname(input.path).toLowerCase());
       if (mediaType === void 0) {
-        return json({
+        return json2({
           ok: false,
           error: "unsupported_image_type",
           path: input.path,
@@ -2690,8 +2807,8 @@ function createViewImageTool(options) {
       }
       const absolute = pathSafety.safePathJoin(projectRoot, input.path);
       const outcome = readWithinBudget(absolute, maxBytes);
-      if (!outcome.ok) return json(failureFor(outcome, input.path, maxBytes));
-      return json({
+      if (!outcome.ok) return json2(failureFor(outcome, input.path, maxBytes));
+      return json2({
         ok: true,
         path: input.path,
         media_type: mediaType,
@@ -2888,8 +3005,8 @@ function createBraveWebSearchAdapter(opts = {}) {
       headers: { "X-Subscription-Token": apiKey, Accept: "application/json" }
     });
     if (!res.ok) throw new Error(`brave_search_failed: HTTP ${res.status}`);
-    const json2 = await res.json();
-    const results = json2?.web?.results ?? [];
+    const json3 = await res.json();
+    const results = json3?.web?.results ?? [];
     return results.map((r) => ({
       title: String(r?.title ?? ""),
       url: String(r?.url ?? ""),
@@ -3051,7 +3168,9 @@ async function isBinaryFile(absolutePath) {
 
 exports.CatastrophicCommandError = CatastrophicCommandError;
 exports.ContextMatchError = ContextMatchError;
+exports.DEFAULT_MAX_AUDIO_BYTES = DEFAULT_MAX_AUDIO_BYTES;
 exports.DEFAULT_MAX_IMAGE_BYTES = DEFAULT_MAX_IMAGE_BYTES;
+exports.DEFAULT_MAX_TEXT_CHARS = DEFAULT_MAX_TEXT_CHARS;
 exports.DEFAULT_TOOL_GUIDANCE = DEFAULT_TOOL_GUIDANCE;
 exports.ReadTracker = ReadTracker;
 exports.ReasoningTools = ReasoningTools;
@@ -3078,6 +3197,7 @@ exports.createRunVitestTool = createRunVitestTool;
 exports.createSearchTextTool = createSearchTextTool;
 exports.createSessionArtifactStore = createSessionArtifactStore;
 exports.createShellTool = createShellTool;
+exports.createTextToSpeechTool = createTextToSpeechTool;
 exports.createTodolistTool = createTodolistTool;
 exports.createUpdatePlanTool = createUpdatePlanTool;
 exports.createViewImageTool = createViewImageTool;