indusagi 0.12.32 → 0.12.34

package/dist/knowledge/guides/authoring-an-agent.md

@@ -0,0 +1,53 @@
+# Authoring an agent
+
+An agent in Smithy is just a small bundle of decisions: a name, a one-line
+description, the system prompt that gives it its voice, the slice of tools it is
+trusted with, and the model that backs it. Get those five things right and the
+rest takes care of itself. This guide is the order I work in.
+
+## Start from a profile, not a blank page
+
+Most agents you want to build are a variation on one of three shapes: a coder
+that edits files and runs commands, a researcher that only reads and
+summarises, or a reviewer that inspects a change and reports. Pick the nearest
+profile and override only what differs. A profile already pins a sane tool
+collection, a model, and a starter prompt, so naming the agent is enough to get
+something that runs:
+
+    defineAgent({ name: "release-notes" }, "researcher")
+
+Then narrow it. Override the description and system prompt to describe *this*
+agent's job, not the generic kind. Leave the tool collection and model alone
+unless you have a concrete reason to change them.
+
+## Name it like a file
+
+The name is a kebab-case identifier — lowercase letters, digits, and hyphens.
+Treat it like a filename, because that is roughly what it is: a stable handle you
+will type, log, and look up. `code-reviewer`, not `Code Reviewer`. Keep it short
+and specific. If two agents would want the same name, one of them is mis-scoped.
+
+## Write the description for a human scanning a list
+
+The description is one line and it is for people, not the model. Imagine a menu
+of twenty agents — the description is what tells a reader which one to pick. Say
+what the agent *does* and what it *touches*. "Summarises a PR diff and flags
+risky changes" beats "a helpful review assistant."
+
+## Let the precedence rules do the merging
+
+You never assemble the full blueprint by hand. `defineAgent` merges three
+layers, highest priority first: your spec, then the named profile, then a
+built-in baseline that fills any remaining gap. The only field with a surprise
+is `tags` — your tags *replace* the profile's rather than merging, so you stay
+in full control of how the agent is catalogued. Everything is validated once at
+the end, so a half-finished spec fails loudly instead of producing a broken
+agent.
+
+## Verify before you trust it
+
+A blueprint that validates is well-formed, not necessarily *correct*. Before you
+wire an agent into anything real, read its system prompt back as if you were the
+model receiving it, confirm the tool collection matches the access you intend,
+and sanity-check the model id. The cheapest bug to fix is the one you catch by
+re-reading your own spec.

package/dist/knowledge/guides/choosing-tools.md

@@ -0,0 +1,49 @@
+# Choosing tools
+
+Every agent is granted exactly one named tool collection. The collection is the
+single most important safety decision you make, because it is the boundary
+between an agent that can only *look* and one that can *change things*. Pick the
+narrowest collection that still lets the agent finish its job.
+
+## The three collections
+
+There are three, and they nest:
+
+- **`read-only`** — the agent can observe but never mutate. It reads files,
+  lists directories, greps and finds across the workspace, searches the web, and
+  fetches pages. Nothing it does leaves a mark on the workspace.
+- **`coding`** — everything in `read-only`, plus the mutating and stateful
+  tools: writing and editing files, running shell commands, managing a running
+  process, and keeping a todo list. This is the working engineer's surface.
+- **`all`** — every registered tool. In practice this equals `coding` today, but
+  it is the right choice when you mean "whatever exists," not a fixed set.
+
+## How to choose
+
+Ask one question: *does this agent need to leave the workspace different than it
+found it?* If the answer is no, use `read-only` and stop. A researcher, a
+reviewer, a summariser, a question-answerer — none of them should be holding the
+write tool. Granting more access than the task needs does not make the agent
+more capable; it just widens the blast radius of a mistake.
+
+If the agent genuinely has to produce edits, run a build, or drive a process,
+use `coding`. Reach for `all` only when you specifically want the agent to pick
+up tools that get registered later without you having to revisit the blueprint.
+
+## Read-only is a real guarantee
+
+It is worth saying plainly: read-only is not a hint to the model, it is the set
+of tools the agent is *handed*. An agent on the `read-only` collection has no
+write, edit, or bash tool to call, so it cannot mutate the workspace even if its
+prompt drifts or it is asked to. That is exactly why you should default to it.
+Promote to `coding` deliberately, as an explicit decision, not because it seems
+convenient.
+
+## Match the collection to the prompt
+
+A mismatch between the prompt and the collection is a common and confusing bug.
+If the system prompt tells the agent to "edit the file and re-run the tests" but
+the collection is `read-only`, the agent will flail trying to call tools it does
+not have. Keep the two in sync: a read-only agent's prompt should describe a
+read-only job, and a coding agent's prompt should acknowledge that its edits are
+real.

package/dist/knowledge/guides/model-selection.md

@@ -0,0 +1,51 @@
+# Model selection
+
+The model is the engine behind every agent. The blueprint stores it as a plain
+string id; the gateway catalog is what knows whether that id is real and what it
+costs. Choosing well is mostly about matching the model's strength to the
+agent's actual workload — and not paying for capability the task never uses.
+
+## Pick for the job, not for the headline
+
+The biggest model is not the right default. Reach for a heavyweight model when
+the work is genuinely hard reasoning — reviewing a subtle change, weighing
+conflicting evidence, planning a multi-step refactor. Reach for a balanced model
+when the work is steady and well-scoped: editing files, summarising, answering
+straightforward questions. The starter profiles encode this — the reviewer leans
+on the heavier model, the coder and researcher on a balanced one — and that is a
+good instinct to copy.
+
+## Know the catalog ids
+
+The model id has to be one the gateway recognises. As of this writing the
+catalog includes Anthropic ids (`claude-opus-4`, `claude-sonnet-4`,
+`claude-haiku-3-5`), OpenAI ids (`gpt-4o`, `gpt-4o-mini`, `o3`, `o4-mini`),
+Google ids (`gemini-2.5-pro`, `gemini-2.5-flash`), and a few others. A blueprint
+will validate as long as the id is a non-empty string, but the *runtime* adapter
+is what checks the id against the registry — so a typo passes the blueprint gate
+and fails later. Copy ids from the catalog rather than typing them from memory.
+
+## Spend deliberately
+
+A model that reasons harder usually costs more per token and runs slower. That is
+worth it for a reviewer that runs occasionally on important diffs; it is wasteful
+for a high-frequency summariser. Think about how often the agent runs and how
+much each run matters, then size the model to that. The cheapest correct answer
+beats the most expensive one.
+
+## Right-size the smaller jobs
+
+A surprising amount of agent work — classifying, extracting, routing, short
+summaries — runs perfectly well on a smaller, faster model. When an agent's task
+is narrow and mechanical, a `*-mini` or `*-flash` class id often does the job at
+a fraction of the cost and latency. Don't reflexively send simple work to a
+flagship model.
+
+## Override, don't fight the profile
+
+When you start from a profile you inherit its model, and most of the time you
+should keep it. Override the model only when the agent's workload differs from
+the profile's assumptions — for example, a researcher that has to do heavy
+synthesis might warrant the heavier model, or a reviewer running on trivial,
+high-volume diffs might be fine on a lighter one. Make the override a conscious
+choice with a reason behind it, the same way you would for the tool collection.

package/dist/knowledge/guides/writing-system-prompts.md

@@ -0,0 +1,53 @@
+# Writing system prompts
+
+The system prompt is where an agent gets its personality and its job. It is the
+one field a profile can give you a head start on but can never finish for you,
+because only you know what *this* agent is supposed to do. A good prompt is
+short, concrete, and honest about the agent's limits.
+
+## Lead with the role, then the rules
+
+Open with one sentence that says who the agent is and what it is for. The model
+anchors hard on the first line, so make it count: "You are a careful researcher
+whose job is to find and explain information, never to change it." Everything
+after that is the handful of rules that keep the agent on the rails.
+
+## Prefer a few sharp rules over many soft ones
+
+A prompt with five specific instructions beats one with fifteen vague ones. Each
+rule should be something the model can actually act on and you could check it
+against later. "Trace each claim back to a source, and say so when sources
+disagree" is actionable. "Be thorough and accurate" is wallpaper — it sounds
+good and changes nothing.
+
+## State the access, and the prohibition
+
+If the agent is read-only, say so in the prompt as well as in the tool
+collection — not because the prompt enforces it (the tool set does that) but
+because it tells the model how to plan. "You have read-only access: inspect
+files and search the web, but make no edits" stops the agent from forming a plan
+that depends on tools it does not have. The collection is the fence; the prompt
+is the sign on the fence.
+
+## Tell it what to do when it is stuck
+
+The behaviour that separates a good agent from a frustrating one is what it does
+under uncertainty. Spell it out. "When a request is ambiguous, state the
+assumption you are making rather than guessing silently." "Say so when the
+evidence is thin." An agent that surfaces its uncertainty is one you can trust;
+an agent that hides it is one you have to babysit.
+
+## Close with the shape of a good answer
+
+End by describing what "done" looks like — the form, not just the content. "Close
+with a concise, structured synthesis a reader could act on without re-reading
+everything." "Report plainly what you changed and why." This gives the model a
+target to write toward instead of trailing off whenever it runs out of tokens.
+
+## Keep it in your own voice
+
+Write the prompt as prose you would be comfortable putting your name on. Avoid
+copying boilerplate from elsewhere; a prompt assembled from borrowed fragments
+reads as incoherent to the model and tends to pull it in three directions at
+once. One clear voice, a few sharp rules, an honest statement of limits — that is
+the whole craft.

package/dist/knowledge/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Smithy knowledge layer — public surface.
+ *
+ * The externalised knowledge pack: a `manifest.json` cataloguing the guide docs
+ * and the markdown bodies under `guides/`, loaded into memory by
+ * {@link loadKnowledge}. A consumer imports the loader from here and reads guides
+ * by id without touching the filesystem layout directly.
+ */
+
+export {
+  loadKnowledge,
+  KnowledgeError,
+} from "./loader";
+export type {
+  KnowledgePack,
+  KnowledgeManifest,
+  GuideManifestEntry,
+  Guide,
+} from "./loader";

package/dist/knowledge/loader.ts

@@ -0,0 +1,200 @@
+/**
+ * `loadKnowledge` — read Smithy's knowledge pack off disk into a {@link KnowledgePack}.
+ *
+ * The knowledge pack used to live as one big inline constant baked into the
+ * source. That made it invisible to anyone editing the prose, impossible to diff
+ * sensibly, and welded the docs to the build. Here it is *externalised*: a
+ * `manifest.json` lists the guides by id, title, file, and summary, and each
+ * guide is a plain markdown file beside it under `guides/`. This loader is the
+ * single seam that turns those files back into structured, in-memory data the
+ * rest of Smithy can consult.
+ *
+ * The manifest is the source of truth for *which* guides exist and how they are
+ * described; the markdown files are the source of truth for their *bodies*. The
+ * loader reads the manifest first, then pulls each referenced file, so a guide
+ * that is listed but missing on disk surfaces as a clear error rather than a
+ * silent gap.
+ */
+
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** One guide's manifest entry: how it is catalogued, plus where its body lives. */
+export interface GuideManifestEntry {
+  /** Stable, file-safe identifier used to look the guide up. */
+  readonly id: string;
+  /** Human-readable title. */
+  readonly title: string;
+  /** Path to the guide's markdown body, relative to the manifest. */
+  readonly file: string;
+  /** One-line description of what the guide covers. */
+  readonly summary: string;
+}
+
+/** The parsed shape of `manifest.json` before bodies are attached. */
+export interface KnowledgeManifest {
+  /** Manifest schema/content version. */
+  readonly version: string;
+  /** The guides this pack ships, in catalogue order. */
+  readonly guides: readonly GuideManifestEntry[];
+}
+
+/** One fully-loaded guide: its manifest metadata plus its markdown body. */
+export interface Guide extends GuideManifestEntry {
+  /** The guide's markdown body, read from {@link GuideManifestEntry.file}. */
+  readonly body: string;
+}
+
+/** The whole knowledge pack: the manifest version plus every loaded guide. */
+export interface KnowledgePack {
+  /** The manifest's declared version. */
+  readonly version: string;
+  /** Every guide, with its body attached, in manifest order. */
+  readonly guides: readonly Guide[];
+  /** Look a guide up by its {@link Guide.id}; `undefined` if absent. */
+  guide(id: string): Guide | undefined;
+}
+
+/** Raised when the knowledge pack cannot be loaded or fails its shape check. */
+export class KnowledgeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "KnowledgeError";
+  }
+}
+
+/** The default knowledge directory: the folder this module lives in. */
+function defaultDir(): string {
+  return dirname(fileURLToPath(import.meta.url));
+}
+
+/**
+ * Load the knowledge pack from `dir` (defaults to this module's own directory).
+ *
+ * Reads and validates `manifest.json`, then reads each guide's markdown body,
+ * resolving file paths relative to the manifest. The returned pack is frozen and
+ * carries a {@link KnowledgePack.guide} lookup. Any missing or malformed input
+ * surfaces as a {@link KnowledgeError}.
+ *
+ * @param dir Optional directory holding `manifest.json` and `guides/`.
+ */
+export async function loadKnowledge(dir?: string): Promise<KnowledgePack> {
+  const root = dir ? resolve(dir) : defaultDir();
+  const manifest = await readManifest(root);
+
+  const guides: Guide[] = [];
+  for (const entry of manifest.guides) {
+    const path = isAbsolute(entry.file) ? entry.file : join(root, entry.file);
+    const body = await readGuideBody(path, entry.id);
+    guides.push({ ...entry, body });
+  }
+
+  return freezePack(manifest.version, guides);
+}
+
+/** Read and shape-check `manifest.json` from `root`. */
+async function readManifest(root: string): Promise<KnowledgeManifest> {
+  const path = join(root, "manifest.json");
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (cause) {
+    throw new KnowledgeError(
+      `could not read knowledge manifest at ${path}: ${describe(cause)}`,
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw new KnowledgeError(
+      `knowledge manifest is not valid JSON (${path}): ${describe(cause)}`,
+    );
+  }
+
+  return validateManifest(parsed, path);
+}
+
+/** Read one guide's markdown body, mapping a read failure to a clear error. */
+async function readGuideBody(path: string, id: string): Promise<string> {
+  try {
+    return await readFile(path, "utf8");
+  } catch (cause) {
+    throw new KnowledgeError(
+      `could not read body for guide "${id}" at ${path}: ${describe(cause)}`,
+    );
+  }
+}
+
+/** Assert that a parsed value has the {@link KnowledgeManifest} shape. */
+function validateManifest(value: unknown, path: string): KnowledgeManifest {
+  if (!isRecord(value)) {
+    throw new KnowledgeError(`knowledge manifest (${path}) is not an object`);
+  }
+  if (typeof value.version !== "string" || value.version.length === 0) {
+    throw new KnowledgeError(
+      `knowledge manifest (${path}) is missing a non-empty "version"`,
+    );
+  }
+  if (!Array.isArray(value.guides)) {
+    throw new KnowledgeError(
+      `knowledge manifest (${path}) is missing a "guides" array`,
+    );
+  }
+
+  const guides = value.guides.map((entry, index) =>
+    validateEntry(entry, index, path),
+  );
+
+  return { version: value.version, guides };
+}
+
+/** Assert that one manifest entry has the {@link GuideManifestEntry} shape. */
+function validateEntry(
+  entry: unknown,
+  index: number,
+  path: string,
+): GuideManifestEntry {
+  if (!isRecord(entry)) {
+    throw new KnowledgeError(
+      `guide entry ${index} in ${path} is not an object`,
+    );
+  }
+  for (const field of ["id", "title", "file", "summary"] as const) {
+    if (typeof entry[field] !== "string" || entry[field].length === 0) {
+      throw new KnowledgeError(
+        `guide entry ${index} in ${path} is missing a non-empty "${field}"`,
+      );
+    }
+  }
+  return {
+    id: entry.id as string,
+    title: entry.title as string,
+    file: entry.file as string,
+    summary: entry.summary as string,
+  };
+}
+
+/** Build the frozen pack and its `guide` lookup over a fixed index. */
+function freezePack(version: string, guides: Guide[]): KnowledgePack {
+  const byId = new Map(guides.map((g) => [g.id, g]));
+  return Object.freeze({
+    version,
+    guides: Object.freeze([...guides]),
+    guide(id: string): Guide | undefined {
+      return byId.get(id);
+    },
+  });
+}
+
+/** Narrow an unknown to a plain object record. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Best-effort human-readable description of a thrown cause. */
+function describe(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}

package/dist/knowledge/manifest.json

@@ -0,0 +1,29 @@
+{
+  "version": "1.0.0",
+  "guides": [
+    {
+      "id": "authoring-an-agent",
+      "title": "Authoring an agent",
+      "file": "guides/authoring-an-agent.md",
+      "summary": "The order of decisions for building an agent: start from a profile, name it like a file, write a human-facing description, and let defineAgent merge and validate."
+    },
+    {
+      "id": "choosing-tools",
+      "title": "Choosing tools",
+      "file": "guides/choosing-tools.md",
+      "summary": "The three nested tool collections (read-only, coding, all), how to pick the narrowest one, and why read-only is a real guarantee rather than a hint."
+    },
+    {
+      "id": "writing-system-prompts",
+      "title": "Writing system prompts",
+      "file": "guides/writing-system-prompts.md",
+      "summary": "How to write a system prompt: lead with the role, prefer a few sharp rules, state the access, say what to do when stuck, and describe a good answer."
+    },
+    {
+      "id": "model-selection",
+      "title": "Model selection",
+      "file": "guides/model-selection.md",
+      "summary": "Matching a catalog model id to an agent's workload, spending deliberately, right-sizing smaller jobs, and overriding a profile's model with a reason."
+    }
+  ]
+}