@symplek/cli 0.0.0-stage → 0.2.0-beta.0

package/dist/models.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * The one place the CLI knows about model ids.
+ *
+ * Providers add and retire models far more often than this CLI is released,
+ * so the CLI does not decide which models exist. Any well-formed id passes
+ * `validate` and `generate`; the provider is the authority on whether it is
+ * live. The list below is only what `symplek add agent` offers in its picker.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODEL_ID_HINT = exports.MODEL_ID_PATTERN = exports.DEFAULT_MODEL = exports.SUGGESTED_MODELS = void 0;
+exports.isModelId = isModelId;
+/** Offered by the interactive picker. Mirrors @symplek/core's default model table. */
+exports.SUGGESTED_MODELS = [
+    "gpt-4o",
+    "gpt-4o-mini",
+    "claude-opus-5-5",
+    "claude-sonnet-5-5",
+    "claude-haiku-5-5",
+    "gemini-3.8-flash",
+    "gemini-3.5-flash-lite",
+];
+/** Used when the caller names no model. */
+exports.DEFAULT_MODEL = exports.SUGGESTED_MODELS[0];
+/**
+ * The shape of a model id: letters, digits, and `. _ : / -`, starting with a
+ * letter or digit. Wide enough for dated snapshots, fine-tune ids and
+ * `vendor/model` routes; narrow enough that an id can be written into YAML or
+ * TypeScript without quoting hazards (no whitespace, quotes or newlines).
+ */
+exports.MODEL_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$";
+const MODEL_ID_REGEX = new RegExp(exports.MODEL_ID_PATTERN);
+/** True when `value` is a well-formed model id. */
+function isModelId(value) {
+    return typeof value === "string" && MODEL_ID_REGEX.test(value);
+}
+/** One-line hint shown when a model id is missing or malformed. */
+exports.MODEL_ID_HINT = `Use a provider model id, for example: ${exports.SUGGESTED_MODELS.join(", ")}`;
+//# sourceMappingURL=models.js.map

package/dist/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AA2BH,8BAEC;AA3BD,sFAAsF;AACzE,QAAA,gBAAgB,GAAG;IAC9B,QAAQ;IACR,aAAa;IACb,iBAAiB;IACjB,mBAAmB;IACnB,kBAAkB;IAClB,kBAAkB;IAClB,uBAAuB;CACf,CAAC;AAEX,2CAA2C;AAC9B,QAAA,aAAa,GAAW,wBAAgB,CAAC,CAAC,CAAC,CAAC;AAEzD;;;;;GAKG;AACU,QAAA,gBAAgB,GAAG,sCAAsC,CAAC;AAEvE,MAAM,cAAc,GAAG,IAAI,MAAM,CAAC,wBAAgB,CAAC,CAAC;AAEpD,mDAAmD;AACnD,SAAgB,SAAS,CAAC,KAAc;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACjE,CAAC;AAED,mEAAmE;AACtD,QAAA,aAAa,GAAG,yCAAyC,wBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC"}

package/dist/naming.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The one place the CLI turns an agent's name into a JavaScript identifier.
+ *
+ * An agent is named in kebab-case (`code-reviewer`) and exported from its
+ * generated file in camelCase (`codeReviewer`). `add`, `validate` and
+ * `generate` all use the rules here, so a name one of them accepts is a name
+ * the others can turn into a file that parses.
+ */
+/** Lowercase letters and digits in hyphen-separated segments, starting with a letter. */
+export declare const KEBAB_CASE_REGEX: RegExp;
+/**
+ * `code-reviewer` to `codeReviewer`. A segment may start with a digit
+ * (`agent-2` to `agent2`), so the hyphen is dropped before digits too.
+ */
+export declare function kebabToCamel(name: string): string;
+/** True when `word` cannot be used as an exported function's name. */
+export declare function isReservedWord(word: string): boolean;
+/** Why `name` cannot be an agent name, or undefined when it can. */
+export declare function agentNameProblem(name: string): string | undefined;
+//# sourceMappingURL=naming.d.ts.map

package/dist/naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yFAAyF;AACzF,eAAO,MAAM,gBAAgB,QAAkC,CAAC;AAahE;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQjE"}

package/dist/naming.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * The one place the CLI turns an agent's name into a JavaScript identifier.
+ *
+ * An agent is named in kebab-case (`code-reviewer`) and exported from its
+ * generated file in camelCase (`codeReviewer`). `add`, `validate` and
+ * `generate` all use the rules here, so a name one of them accepts is a name
+ * the others can turn into a file that parses.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEBAB_CASE_REGEX = void 0;
+exports.kebabToCamel = kebabToCamel;
+exports.isReservedWord = isReservedWord;
+exports.agentNameProblem = agentNameProblem;
+/** Lowercase letters and digits in hyphen-separated segments, starting with a letter. */
+exports.KEBAB_CASE_REGEX = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/** Words that cannot be the name of an exported function. */
+const RESERVED_WORDS = new Set([
+    "arguments", "await", "break", "case", "catch", "class", "const", "continue",
+    "debugger", "default", "delete", "do", "else", "enum", "eval", "export",
+    "extends", "false", "finally", "for", "function", "if", "implements",
+    "import", "in", "instanceof", "interface", "let", "new", "null", "package",
+    "private", "protected", "public", "return", "static", "super", "switch",
+    "this", "throw", "true", "try", "typeof", "var", "void", "while", "with",
+    "yield",
+]);
+/**
+ * `code-reviewer` to `codeReviewer`. A segment may start with a digit
+ * (`agent-2` to `agent2`), so the hyphen is dropped before digits too.
+ */
+function kebabToCamel(name) {
+    return name.replace(/-([a-z0-9])/g, (_, char) => char.toUpperCase());
+}
+/** True when `word` cannot be used as an exported function's name. */
+function isReservedWord(word) {
+    return RESERVED_WORDS.has(word);
+}
+/** Why `name` cannot be an agent name, or undefined when it can. */
+function agentNameProblem(name) {
+    if (!exports.KEBAB_CASE_REGEX.test(name)) {
+        return "Agent name must be kebab-case: lowercase letters, numbers and hyphens, starting with a letter (e.g. my-agent)";
+    }
+    if (isReservedWord(kebabToCamel(name))) {
+        return `"${name}" is a JavaScript reserved word, so it cannot name the exported agent function. Pick another name (e.g. ${name}-agent)`;
+    }
+    return undefined;
+}
+//# sourceMappingURL=naming.js.map

package/dist/naming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAoBH,oCAEC;AAGD,wCAEC;AAGD,4CAQC;AApCD,yFAAyF;AAC5E,QAAA,gBAAgB,GAAG,+BAA+B,CAAC;AAEhE,6DAA6D;AAC7D,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU;IAC5E,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ;IACvE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY;IACpE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS;IAC1E,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ;IACvE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IACxE,OAAO;CACR,CAAC,CAAC;AAEH;;;GAGG;AACH,SAAgB,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AAC/E,CAAC;AAED,sEAAsE;AACtE,SAAgB,cAAc,CAAC,IAAY;IACzC,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,oEAAoE;AACpE,SAAgB,gBAAgB,CAAC,IAAY;IAC3C,IAAI,CAAC,wBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,OAAO,+GAA+G,CAAC;IACzH,CAAC;IACD,IAAI,cAAc,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QACvC,OAAO,IAAI,IAAI,2GAA2G,IAAI,SAAS,CAAC;IAC1I,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/templates/agent/agent.ts.template

@@ -0,0 +1,41 @@
+/**
+ * {{name}} Agent
+ * TypeScript agent definition
+ * Created with: symplek add agent {{name}}
+ *
+ * Before using this agent, set a provider key in the environment (for
+ * example OPENAI_API_KEY), or call
+ * Symplek.configure({ provider, apiKey }) from @symplek/core/server.
+ */
+import { AgentUnit, createContext } from "@symplek/core";
+import { ai } from "@symplek/core/server";
+
+/**
+ * Run the {{name}} agent with a prompt.
+ * Returns an AgentUnit<string> — chain operators (.retry, .timeout, …) before calling .run().
+ */
+export function {{agentName}}(prompt: string): AgentUnit<string> {
+  return AgentUnit.from((_ctx) =>
+    ai(prompt, {
+      model: "{{model}}",
+      system: `You are {{name}}, a helpful AI assistant.
+
+Your responsibilities:
+- Answer questions clearly and accurately
+- Provide helpful explanations
+
+Be concise, accurate, and friendly.`,
+    }),
+  );
+}
+
+export type AgentResult = Awaited<ReturnType<ReturnType<typeof {{agentName}}>["run"]>>;
+
+/**
+ * Convenience helper: run the agent and return its string value.
+ */
+export async function run(prompt: string): Promise<string> {
+  const ctx = createContext();
+  const result = await {{agentName}}(prompt).run(ctx);
+  return result.value as string;
+}

package/dist/templates/agent/general.yaml.template

@@ -0,0 +1,34 @@
+# General conversational agent
+# Created with: symplek add agent {{name}} --type general
+
+name: {{name}}
+version: "1.0.0"
+
+model: "{{model}}"
+
+systemPrompt: |
+  You are {{name}}, a helpful AI assistant.
+
+  Your responsibilities:
+  - Answer questions clearly and accurately
+  - Provide helpful explanations
+  - Admit when you don't know something
+  - Be friendly and professional
+
+  Guidelines:
+  - Be concise but thorough
+  - Ask clarifying questions when needed
+  - Provide examples when helpful
+
+temperature: 0.7
+maxTokens: 2048
+
+# Optional: enable tools when you have defined them in your project.
+# tools:
+#   - search
+#   - calculator
+
+# Optional: episodic memory — store recent turns for context.
+# memory:
+#   episodic: true
+#   maxEpisodes: 10

package/dist/templates/agent/researcher.yaml.template

@@ -0,0 +1,42 @@
+# Research-focused agent
+# Created with: symplek add agent {{name}} --type researcher
+
+name: {{name}}
+version: "1.0.0"
+
+model: "{{model}}"
+
+systemPrompt: |
+  You are {{name}}, an expert research assistant.
+
+  Your responsibilities:
+  - Conduct thorough research on given topics
+  - Synthesize information from multiple sources
+  - Provide well-structured summaries
+  - Cite sources when available
+  - Identify knowledge gaps
+
+  Research methodology:
+  1. Understand the research question
+  2. Break down into sub-questions
+  3. Gather relevant information
+  4. Analyze and synthesize findings
+  5. Present conclusions with evidence
+
+  Output format:
+  - Start with key findings
+  - Provide supporting details
+  - Note limitations and uncertainties
+  - Suggest areas for further research
+
+temperature: 0.5
+maxTokens: 4096
+
+tools:
+  - search
+  - fetch_url
+
+# Optional: episodic memory to track research threads across turns.
+# memory:
+#   episodic: true
+#   maxEpisodes: 20

package/dist/templates/agent/reviewer.yaml.template

@@ -0,0 +1,51 @@
+# Code review agent
+# Created with: symplek add agent {{name}} --type reviewer
+
+name: {{name}}
+version: "1.0.0"
+
+model: "{{model}}"
+
+systemPrompt: |
+  You are {{name}}, an expert code reviewer.
+
+  Your responsibilities:
+  - Review code for correctness, style, and best practices
+  - Identify bugs, security issues, and performance problems
+  - Suggest improvements and alternatives
+  - Explain reasoning behind suggestions
+  - Be constructive and educational
+
+  Review priorities (in order):
+  1. Security vulnerabilities
+  2. Correctness bugs
+  3. Performance issues
+  4. Code style and readability
+  5. Best practices and patterns
+  6. Documentation
+
+  Guidelines:
+  - Be specific with line numbers and code examples
+  - Explain WHY something is an issue
+  - Provide concrete fix suggestions
+  - Acknowledge good code when you see it
+  - Consider context and trade-offs
+
+  Severity levels:
+  - CRITICAL: Security vulnerabilities, data loss risks
+  - HIGH: Bugs that will cause failures
+  - MEDIUM: Performance issues, poor patterns
+  - LOW: Style issues, minor improvements
+  - SUGGESTION: Nice-to-have improvements
+
+temperature: 0.3
+maxTokens: 4096
+
+tools:
+  - read_file
+  - search_code
+
+# Optional: episodic memory to track ongoing review context.
+# memory:
+#   episodic: true
+#   maxEpisodes: 15

package/dist/templates/project/full/.github/workflows/ci.yml.template

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm test
+
+      - name: Build
+        run: pnpm build

package/dist/templates/project/full/.gitignore.template

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.env
+.env.*
+!.env.example
+*.log

package/dist/templates/project/full/Dockerfile.template

@@ -0,0 +1,43 @@
+# {{name}} — Symplek agent runtime image.
+#
+# Multi-stage build:
+#   1. Install all deps + compile TypeScript to dist/.
+#   2. Ship a slim runtime image with only production deps + dist/.
+#
+# Build:   docker build -t {{name}} .
+# Run:     docker run --rm -e OPENAI_API_KEY=$OPENAI_API_KEY {{name}}
+
+# ─── Stage 1: build ──────────────────────────────────────────────────────────
+FROM node:20-alpine AS build
+WORKDIR /app
+RUN corepack enable
+
+# Copy lockfile if present (won't fail if it's missing).
+COPY package.json ./
+COPY pnpm-lock.yaml* ./
+
+RUN pnpm install
+
+COPY tsconfig.json ./
+COPY src ./src
+COPY agents ./agents
+
+RUN pnpm build
+
+# ─── Stage 2: runtime ────────────────────────────────────────────────────────
+FROM node:20-alpine
+WORKDIR /app
+RUN corepack enable && adduser -D -u 1001 symplek
+
+COPY package.json ./
+COPY pnpm-lock.yaml* ./
+
+RUN pnpm install --prod
+
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/agents ./agents
+
+USER symplek
+ENV NODE_ENV=production
+
+CMD ["node", "dist/src/index.js"]

package/dist/templates/project/full/README.md.template

@@ -0,0 +1,77 @@
+# {{name}}
+
+{{description}}
+
+Built with [Symplek](https://github.com/symplek/symplek) — composable AI agents for TypeScript.
+
+---
+
+## Setup
+
+```bash
+pnpm install                      # or npm install / yarn / bun
+export OPENAI_API_KEY=sk-...      # provider env var from src/symplek.config.ts
+pnpm dev                          # watch mode
+pnpm start                        # one-shot
+```
+
+To switch providers, edit `src/symplek.config.ts` and install the matching SDK
+(`pnpm add @anthropic-ai/sdk` for Anthropic, etc.). Symplek auto-detects which
+provider is configured at runtime.
+
+---
+
+## Project layout
+
+```
+{{name}}/
+├── src/
+│   ├── index.ts          # entry — runs the example agent
+│   ├── symplek.config.ts    # Symplek runtime configuration (provider, API key)
+│   └── tools/index.ts    # composable helpers (resilient, withProvenance)
+├── agents/
+│   └── {{agentName}}.yaml   # declarative agent — `symplek generate` compiles it
+└── tests/
+    └── example.test.ts   # vitest unit tests
+```
+
+---
+
+## What's where
+
+- **`src/symplek.config.ts`** — registers your AI provider. Edit here to swap
+  OpenAI for Anthropic, change the default model, set a base URL, etc.
+- **`src/tools/index.ts`** — your project's local helpers. Compose `AgentUnit`
+  operators into project-specific patterns here so the rest of your code stays
+  readable.
+- **`agents/`** — YAML agent definitions. Run `symplek generate` to compile them
+  into typed TypeScript wrappers next to them, as `agents/<name>.ts`.
+
+---
+
+## Scripts
+
+| Command | What it does |
+|---|---|
+| `pnpm dev` | Run the entry in watch mode via `tsx` |
+| `pnpm start` | Run once |
+| `pnpm build` | Compile TypeScript to `dist/` |
+| `pnpm typecheck` | TypeScript check without emit |
+| `pnpm test` | Run vitest once |
+| `pnpm test:watch` | Run vitest in watch mode |
+
+---
+
+## Next steps
+
+- Replace the example in `src/index.ts` with your real agent.
+- Edit `agents/{{agentName}}.yaml`, then run `symplek generate` to add typed wrappers.
+- Add more agents in `agents/`; the CLI handles wiring.
+- See [github.com/symplek/symplek](https://github.com/symplek/symplek) for the operator
+  reference (consensus, debate, dialectic, rehearse, replay, supervised, etc.).
+
+---
+
+## License
+
+ISC

package/dist/templates/project/full/agents/example.yaml.template

@@ -0,0 +1,16 @@
+# Symplek agent definition — declarative form.
+#
+# Compile to TypeScript with:
+#   pnpm exec symplek generate
+#
+# This produces `agents/{{agentName}}.ts` that you can import and call
+# from your application code. YAML lets non-engineers tune prompts without
+# touching the source.
+
+name: {{agentName}}
+description: Summarises text in one clear sentence.
+model: "{{model}}"
+
+systemPrompt: |
+  You summarise the user's input in exactly one clear sentence.
+  Never embellish. Never editorialise. Faithful to the input only.

package/dist/templates/project/full/package.json.template

@@ -0,0 +1,30 @@
+{
+  "name": "{{name}}",
+  "version": "{{version}}",
+  "description": "{{description}}",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@symplek/core": "^1.0.0-beta.1",
+    "zod": "^3.25.76",
+    "openai": "^4.104.0"
+  },
+  "devDependencies": {
+    "@symplek/cli": "^{{cliVersion}}",
+    "@types/node": "^22.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20.19"
+  }
+}

package/dist/templates/project/full/src/index.ts.template

@@ -0,0 +1,43 @@
+import "./symplek.config.js";
+import { createContext } from "@symplek/core";
+import { Symplek } from "@symplek/core/server";
+
+/**
+ * {{name}} — a minimal Symplek agent.
+ *
+ * Demonstrates the core pattern:
+ *   1. `Symplek(prompt)` builds an AI call.
+ *   2. `.coordinate()` lifts it into the AgentUnit<T> algebra.
+ *   3. Layer safety operators on top (retry, timeout, fallback, …).
+ *   4. `.run(ctx)` executes and returns a TrackedResult.
+ *
+ * Scripts:
+ *   pnpm dev    — watch mode (re-runs on file change)
+ *   pnpm start  — one-shot
+ */
+
+if (!process.env.OPENAI_API_KEY) {
+  console.error("[{{name}}] OPENAI_API_KEY is not set.");
+  console.error("Set it and re-run:  export OPENAI_API_KEY=sk-...");
+  process.exit(1);
+}
+
+async function main(): Promise<void> {
+  const ctx = createContext();
+  const input = "The quick brown fox jumps over the lazy dog.";
+
+  const result = await Symplek(`Summarise in one sentence: ${input}`)
+    .coordinate()
+    .retry(2)
+    .timeout(15_000)
+    .run(ctx);
+
+  console.log("Input:      ", input);
+  console.log("Summary:    ", result.value);
+  console.log("Confidence: ", result.confidence);
+}
+
+main().catch((err: unknown) => {
+  console.error("[{{name}}] agent failed:", err);
+  process.exit(1);
+});

package/dist/templates/project/full/src/symplek.config.ts.template

@@ -0,0 +1,20 @@
+/**
+ * Symplek runtime configuration for {{name}}.
+ *
+ * Imported for side effect by `src/index.ts` before any agent runs.
+ * Set OPENAI_API_KEY in your environment:
+ *
+ *   export OPENAI_API_KEY=sk-...
+ *
+ * To swap providers, change `provider` and the matching env var. Symplek
+ * supports `openai`, `anthropic`, and `google` out of the box — install
+ * the corresponding SDK (`pnpm add @anthropic-ai/sdk` etc.) and update
+ * this file.
+ */
+import { Symplek } from "@symplek/core/server";
+
+Symplek.configure({
+  provider: "openai",
+  apiKey: process.env.OPENAI_API_KEY ?? "",
+  model: "{{model}}",
+});

package/dist/templates/project/full/src/tools/index.ts.template

@@ -0,0 +1,73 @@
+/**
+ * Project-local helpers for {{name}}.
+ *
+ * Compose Symplek operators into patterns specific to your project here so
+ * your business code stays declarative. Each helper is one operator chain.
+ */
+import {
+  type AgentUnit,
+  isTracked,
+  type ResultSource,
+  type TrackedResult,
+} from "@symplek/core";
+
+export interface ProvenanceOptions {
+  /** Source category — one of Symplek's `ResultSource` literals. */
+  source: ResultSource;
+  /** Caller's confidence in this value, in [0, 1]. */
+  confidence: number;
+  /** Optional identifier of the verifier (audit trail). */
+  verifiedBy?: string;
+}
+
+/**
+ * Wrap an `AgentUnit<T>` so its output carries provenance metadata.
+ *
+ * Downstream callers can introspect `result.value`, `result.source`,
+ * `result.confidence` — Symplek's TrackedResult shape — without any extra
+ * plumbing.
+ */
+export function withProvenance<T>(
+  unit: AgentUnit<T>,
+  opts: ProvenanceOptions,
+): AgentUnit<TrackedResult<T>> {
+  return unit.tracked({
+    source: opts.source,
+    confidence: opts.confidence,
+    verifiedBy: opts.verifiedBy,
+  });
+}
+
+export interface ResilienceOptions<T> {
+  /** Max attempts including the first. Default 3. */
+  maxAttempts?: number;
+  /** Hard timeout in milliseconds. Default 15s. */
+  timeoutMs?: number;
+  /** Static fallback value if all attempts fail. */
+  fallback?: T;
+}
+
+/**
+ * Apply the standard resilience triad: retry on transient failure, hard
+ * timeout, fallback to a known-safe value if all else fails.
+ *
+ * @example
+ *   const safe = resilient(
+ *     Symplek(prompt).coordinate(),
+ *     { maxAttempts: 3, timeoutMs: 10_000, fallback: "" },
+ *   );
+ */
+export function resilient<T>(
+  unit: AgentUnit<T>,
+  options: ResilienceOptions<T> = {},
+): AgentUnit<T> {
+  const { maxAttempts = 3, timeoutMs = 15_000, fallback } = options;
+  let chain = unit.retry(maxAttempts).timeout(timeoutMs);
+  if (fallback !== undefined) {
+    chain = chain.orElse(fallback);
+  }
+  return chain;
+}
+
+/** Re-export Symplek's tracked-result type guard for convenience. */
+export { isTracked };